/ Hex Artifact Content
Login

Artifact 6c9386f4be831a293bc7bac803f735e12a666ac1:


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 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2f20: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2f30: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f40: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2f50: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2f60: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2f70: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
2f80: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
2f90: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
2fa0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
2fb0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
2fc0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
2fd0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
2fe0: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
2ff0: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
3030: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
3040: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
3050: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3060: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3070: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3080: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3090: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
30a0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
30b0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
30c0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30d0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
30e0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
30f0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
3100: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
3110: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
3120: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
3130: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
3140: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
3150: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3160: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3170: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3190: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
31a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
31b0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
31c0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
31d0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
31e0: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
31f0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
3200: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
3210: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
3220: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
3230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
3240: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3250: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3260: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3270: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3280: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3290: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
32a0: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
32b0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
32c0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
32d0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
32e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
32f0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
3300: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
3310: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
3320: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
3330: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
3340: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3350: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3360: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3370: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3380: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3390: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
33a0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
33b0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
33c0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33d0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
33e0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
33f0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3400: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3410: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3420: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3430: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3440: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3450: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3460: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3470: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3480: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3490: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
34a0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
34b0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
34c0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
34d0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
34e0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
34f0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3500: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3510: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3520: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3530: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3540: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3550: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3560: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3570: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3580: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3590: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
35a0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
35b0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
35c0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
35d0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
35e0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
35f0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3600: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3610: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3620: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3630: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3640: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3650: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3660: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3670: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3680: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3690: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
36a0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
36b0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
36c0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
36d0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
36e0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
36f0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3700: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3710: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3720: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3730: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3740: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3750: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3760: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3770: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3780: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3790: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
37a0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
37b0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
37c0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
37d0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
37e0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
37f0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3800: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3810: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3820: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3830: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3840: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3850: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3860: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3870: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3880: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3890: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
38a0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
38b0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
38c0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
38d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
38e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
3900: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3910: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3920: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3930: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3940: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3950: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3960: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3970: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3980: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3990: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
39a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
39b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
39c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
39d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
39e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
39f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3a00: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3a10: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3a20: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3a30: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3a40: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3a50: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3a60: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3a70: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3a80: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3a90: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3aa0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ab0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3ac0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3ad0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3ae0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3af0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3b00: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3b10: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3b20: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3b30: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3b40: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3b50: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3b60: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3b70: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3b80: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3b90: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3ba0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3bb0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3bc0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3bd0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3bf0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3c00: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3c10: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3c20: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3c30: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3c40: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3c50: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3c60: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3c70: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3c80: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3c90: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3ca0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3cb0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3cc0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3cd0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3ce0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3cf0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3d00: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3d10: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3d20: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3d30: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3d40: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3d50: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3d60: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3d70: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3d80: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3d90: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3da0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3db0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3dc0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3dd0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3de0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3df0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e00: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3e10: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3e20: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3e30: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3e40: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3e50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3e60: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3e70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3e80: 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61   not close [data
3e90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
3ea0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
3eb0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
3ec0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3ed0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3ef0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
3f00: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f10: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
3f20: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
3f30: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
3f40: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
3f50: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
3f60: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3f70: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3f80: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3f90: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69  g..** </ul>.*/.i
3fa0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
3fb0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
3fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
3fe0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
3ff0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
4000: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
4030: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4040: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4050: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4060: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4070: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4080: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40b0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
40c0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
40d0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
40e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
4100: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
4110: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
4120: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
4130: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4140: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4150: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4160: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4170: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4180: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4190: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
41a0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41b0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41c0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41d0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41e0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41f0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4200: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4210: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4220: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4230: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4240: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4250: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4260: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4270: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4290: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
42a0: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
42b0: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
42c0: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
42d0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
42e0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
42f0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4300: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4310: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4320: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
4330: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4340: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4350: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4360: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4380: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4390: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
43a0: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
43b0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
43c0: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
43d0: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
43e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
43f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4400: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4410: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4420: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
4430: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4450: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4460: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4470: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4490: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
44a0: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
44b0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
44d0: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
44e0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
44f0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4510: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4520: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
4530: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4540: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4560: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4570: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4580: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4590: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
45a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
45b0: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
45c0: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
45d0: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
45e0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
45f0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4600: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4610: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4620: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
4630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4640: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4650: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4660: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4670: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4690: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
46a0: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
46b0: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
46c0: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
46d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
46e0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
46f0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4700: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4710: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4720: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
4730: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4740: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4750: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4760: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4770: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4780: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
47b0: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
47c0: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
47d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
47e0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
47f0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4800: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4810: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
4830: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4840: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4850: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4860: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4870: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4880: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4890: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
48a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
48b0: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
48c0: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
48d0: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
48f0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4900: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4910: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4920: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4930: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4940: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4950: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4980: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4990: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
49a0: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
49b0: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
49c0: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
49d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
49e0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
49f0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a10: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a20: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4a30: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4a40: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4a50: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4a60: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4a70: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4a80: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4a90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4aa0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4ab0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4ac0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ad0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ae0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4af0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b00: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4b10: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4b20: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4b30: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4b40: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4b50: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4b60: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4b70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4b80: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4b90: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4ba0: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4bb0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4bc0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4bd0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4be0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4bf0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c00: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4c10: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4c20: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4c30: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4c40: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4c50: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4c60: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4c70: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4c80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4c90: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4ca0: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4cb0: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4cc0: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4cd0: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4ce0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4cf0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d00: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4d10: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4d20: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4d30: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4d40: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4d50: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4d60: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4d70: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4d80: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4d90: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4da0: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4db0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4dc0: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4dd0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4de0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4df0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e00: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4e10: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4e20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4e30: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4e40: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4e50: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4e60: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4e70: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4e80: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4e90: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4ea0: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4eb0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4ec0: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4ed0: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4ee0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4ef0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4f00: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4f10: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4f20: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4f30: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4f40: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4f50: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4f60: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4f70: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4f80: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4f90: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4fa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fb0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4fc0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4fd0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4fe0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ff0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5000: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5010: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5030: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5050: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5070: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5080: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5090: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
50a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50b0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
50c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50d0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
50e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
50f0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5100: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5110: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5130: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5150: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5170: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5180: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5190: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
51a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51b0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
51c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51d0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
51e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51f0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5200: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5210: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5220: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5230: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5240: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5250: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
52c0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
52d0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5380: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5390: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5530: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5540: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5550: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5570: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5580: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5590: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55b0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55d0: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55f0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5600: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5610: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
5620: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5630: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5640: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5650: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5660: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5670: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5680: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5690: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56c0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56e0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5700: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5710: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5720: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5740: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5750: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5760: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5770: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5780: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5790: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
57a0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
57b0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
57c0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
57d0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57f0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5800: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5810: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5820: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5830: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5840: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5850: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5860: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5870: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5880: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5890: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
58b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58c0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
58d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58f0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5900: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5910: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5920: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5930: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5940: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5950: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5960: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5970: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5980: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
59b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59c0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5a10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5a30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5aa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ac0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ad0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ae0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5af0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5b00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5b30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5b40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5bb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bf0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5c30: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c80: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ca0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cb0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5cc0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5cd0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ce0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d00: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5d10: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5d20: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d50: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d60: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d70: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5da0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5db0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5dc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5dd0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5df0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5e00: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5e10: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5e20: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5e30: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e40: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e50: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e60: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e70: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e80: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e90: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5ea0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5eb0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5ec0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5ed0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ee0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5ef0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5f00: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5f10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5f20: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5f30: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f50: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f60: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f70: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f80: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5fa0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5fb0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5fc0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5fd0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fe0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5ff0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6000: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6010: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6020: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6030: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6040: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6050: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6060: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6070: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6080: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6090: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
60a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
60b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
60c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
60d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6100: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6110: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6120: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6130: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6140: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6150: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6160: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6170: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6180: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6190: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
61a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
61b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
61c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
61d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6200: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6210: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6220: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6230: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6240: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6250: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6260: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6270: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6280: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6290: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
62a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
62b0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
62c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62d0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62f0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6300: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6310: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6320: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6350: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6370: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6390: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
63a0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
63b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
63c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
63d0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63e0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6400: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6410: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6430: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6440: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6450: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6460: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6470: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6480: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6490: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
64a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
64b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
64c0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
64d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64e0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64f0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6500: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6510: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6520: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6540: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6550: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6560: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6570: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6580: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6590: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
65a0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
65b0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
65c0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
65d0: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65e0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65f0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6600: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6610: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6620: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6630: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6640: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6650: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6660: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6670: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6680: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6690: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
66a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
66b0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
66c0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
66d0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66e0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66f0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6700: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6710: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6720: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6730: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6740: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6760: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6770: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6780: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6790: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
67a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
67b0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
67c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
67d0: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67e0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67f0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6800: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6810: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6820: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6830: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6840: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6850: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6860: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6870: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6880: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6890: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
68a0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
68b0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
68c0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
68d0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68e0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68f0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6900: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6920: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6930: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6940: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6950: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6960: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6970: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6980: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69a0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
69b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
69c0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
69d0: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69e0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69f0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6a00: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6a10: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6a20: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6a30: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a40: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a50: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a60: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a80: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a90: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6aa0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6ab0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ac0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6ad0: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ae0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6af0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6b00: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6b10: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6b20: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6b30: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b40: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b50: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b60: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b70: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b80: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b90: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6ba0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6bb0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6bc0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6bd0: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6be0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bf0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6c10: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6c20: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6c30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c40: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c50: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c60: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c70: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c90: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6ca0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6cb0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6cc0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6cd0: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ce0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cf0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6d00: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6d10: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6d20: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6d30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d40: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d50: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d60: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d70: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d80: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d90: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6da0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6db0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6dc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6de0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6df0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6e00: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6e10: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6e20: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e50: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e60: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e70: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e80: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e90: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6ea0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6eb0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6ec0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6ed0: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ee0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6ef0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6f00: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6f10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6f20: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6f30: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f40: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f50: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f60: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f70: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f80: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f90: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6fa0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6fb0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6fc0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6fd0: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fe0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6ff0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7000: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7010: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7020: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7030: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7040: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7050: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7060: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7070: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7080: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7090: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
70a0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
70b0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
70c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
70d0: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70e0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70f0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7100: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7110: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7120: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7130: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7140: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7150: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7160: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7170: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7180: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7190: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
71a0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
71b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
71c0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
71d0: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71e0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71f0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7200: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7220: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7230: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7240: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7250: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7260: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7270: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7280: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7290: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
72a0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
72b0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
72c0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
72d0: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72e0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72f0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7300: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7310: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7320: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7330: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7340: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7350: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7360: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7370: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7380: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7390: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73a0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
73b0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
73c0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
73d0: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73f0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7400: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7410: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7420: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7430: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7440: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7450: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7460: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7470: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7480: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7490: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
74a0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
74b0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
74c0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
74d0: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74e0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74f0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7500: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7510: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7520: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7530: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7540: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7550: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7560: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7570: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7580: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7590: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
75a0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
75b0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
75c0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
75d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75e0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75f0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7600: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7610: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7620: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7630: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7640: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7650: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7660: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7670: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7680: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7690: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
76a0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
76b0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
76c0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
76d0: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76e0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76f0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7700: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7710: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7720: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7730: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7740: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7750: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7760: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7770: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7780: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7790: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
77a0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
77b0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
77c0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
77d0: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77e0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7800: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7810: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7820: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7830: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7840: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7850: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7860: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7870: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7880: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7890: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
78a0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
78b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
78c0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
78d0: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78e0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78f0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7900: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7910: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7920: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7930: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7940: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7950: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7960: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7970: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7980: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7990: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
79a0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
79b0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
79c0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
79d0: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79e0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7a00: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7a10: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7a20: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7a30: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a40: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a50: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a60: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a80: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7aa0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ae0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7b10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b20: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b40: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b60: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7ba0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7bb0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7bc0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7bd0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7be0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bf0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7c00: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7c10: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7c20: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c40: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c50: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c60: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c70: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c80: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c90: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7ca0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7cb0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7cc0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7cd0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ce0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cf0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7d00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7d10: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7d20: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7d30: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d40: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d50: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d60: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d70: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d80: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d90: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7da0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7db0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7dc0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7dd0: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7de0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7df0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7e00: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7e10: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7e20: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7e30: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e40: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e50: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e60: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e70: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e80: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e90: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7ea0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7eb0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7ec0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7ed0: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ee0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7ef0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7f00: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7f10: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7f20: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7f30: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f50: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f60: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f70: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f80: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f90: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7fa0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7fb0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7fc0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7fd0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fe0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7ff0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8000: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8010: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8020: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8030: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8040: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8050: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8060: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8070: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8080: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8090: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
80a0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
80b0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
80d0: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80e0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80f0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8100: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8110: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8120: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8130: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8140: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8150: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8160: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8170: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8180: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8190: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
81a0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
81b0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
81c0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
81d0: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81f0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8200: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8210: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8220: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8230: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8240: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8250: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8260: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8270: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8280: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8290: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
82a0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
82b0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
82c0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
82d0: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82f0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8300: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8310: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8320: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
8330: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8340: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8350: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8360: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8370: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8380: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8390: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
83a0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
83b0: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
83c0: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
83d0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83e0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
8400: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
8410: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8420: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
8430: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8440: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8450: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8460: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8470: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8480: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8490: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
84a0: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
84b0: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
84c0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
84d0: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84e0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
8500: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
8510: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
8520: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8530: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8540: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8550: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8560: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8570: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8580: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8590: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
85a0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
85b0: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
85c0: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
85d0: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85e0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85f0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
8600: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8610: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
8620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
8630: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8640: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8650: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8660: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8670: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8680: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8690: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
86a0: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
86b0: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
86c0: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
86d0: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86e0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86f0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
8700: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
8710: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
8720: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
8730: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8740: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8750: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8760: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8770: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8780: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8790: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
87a0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
87b0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
87c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
87d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87e0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87f0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8800: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8810: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8820: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8830: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8840: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8850: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8860: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8870: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8890: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
88a0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
88b0: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
88c0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
88d0: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88e0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88f0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8900: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8910: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8920: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8930: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8940: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8950: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8960: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8970: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8980: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8990: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
89a0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
89b0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
89c0: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
89d0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89e0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89f0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8a00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8a10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8a20: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8a30: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a40: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a50: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a60: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a70: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a80: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a90: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8aa0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8ab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8ac0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8ad0: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ae0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8af0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8b00: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8b10: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8b20: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8b30: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b40: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b50: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b60: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b80: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b90: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8ba0: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8bb0: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8bc0: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8bd0: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8be0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bf0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8c00: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8c10: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8c20: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8c30: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c40: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c50: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c60: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c70: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c80: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8ca0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8cb0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8cc0: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8cd0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ce0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cf0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8d00: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8d10: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8d20: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8d30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d40: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d50: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d70: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d80: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d90: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8da0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8db0: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8dc0: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8dd0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8de0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8df0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8e00: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8e10: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8e20: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8e30: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e50: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e60: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e70: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e80: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e90: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8ea0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8eb0: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8ec0: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8ed0: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ee0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8ef0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8f00: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8f10: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8f20: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8f30: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f40: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f50: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f60: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f70: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f90: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8fa0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8fb0: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8fc0: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8fd0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fe0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8ff0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
9000: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
9010: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
9020: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
9030: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9040: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9050: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9060: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9070: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9080: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9090: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
90a0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
90b0: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
90c0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
90d0: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90e0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90f0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
9100: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
9110: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
9120: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
9130: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9140: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9150: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9160: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9170: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9180: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9190: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
91a0: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
91b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
91c0: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
91d0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91e0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91f0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
9200: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
9210: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
9220: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
9230: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9240: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9250: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9260: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9270: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9280: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9290: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
92a0: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
92b0: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
92c0: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
92d0: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92e0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92f0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
9300: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
9310: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
9320: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
9330: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9340: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9350: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9360: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9370: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9380: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9390: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
93a0: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
93b0: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
93c0: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
93d0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93e0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93f0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
9400: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
9410: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
9420: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
9430: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9440: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9450: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9460: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9480: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9490: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
94a0: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
94b0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
94c0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
94d0: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9500: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9510: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9520: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
9530: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9550: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9560: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9570: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9580: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9590: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
95a0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
95b0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
95c0: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
95d0: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95e0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95f0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
9600: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
9610: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
9620: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
9630: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9640: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9650: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9660: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9670: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9690: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
96a0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
96b0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
96c0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
96d0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96e0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96f0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
9700: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
9710: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
9720: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
9730: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9740: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9750: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9760: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9770: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9780: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9790: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
97a0: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
97b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
97c0: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
97d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97e0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97f0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
9800: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
9810: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
9820: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
9830: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9840: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9850: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9860: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9870: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9880: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9890: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
98a0: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
98b0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
98c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
98d0: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98f0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
9900: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
9910: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
9920: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
9930: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9940: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9950: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9960: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9970: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9980: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9990: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
99a0: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
99b0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
99c0: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
99d0: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99e0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99f0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9a00: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9a10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9a20: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9a30: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a40: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a50: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a60: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a70: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a80: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a90: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9aa0: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9ab0: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9ac0: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9ad0: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ae0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9af0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9b00: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9b10: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9b20: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9b30: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b40: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b50: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b70: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b80: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9ba0: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9bb0: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9bc0: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9bd0: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9be0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bf0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9c00: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9c10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9c20: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9c30: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c40: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c50: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c60: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c70: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c80: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9ca0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9cb0: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9cc0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9cd0: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ce0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cf0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9d00: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9d10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9d20: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9d30: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d40: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d50: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d60: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d70: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d80: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d90: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9da0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9db0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9dc0: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9dd0: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9de0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9df0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9e00: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9e10: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9e20: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9e30: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e40: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e50: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e60: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e70: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e80: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e90: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9ea0: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9eb0: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9ec0: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9ed0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ee0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9ef0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9f00: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9f10: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9f20: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f40: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f50: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f60: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f70: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f80: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f90: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9fa0: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9fb0: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9fc0: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9fd0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a000: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a010: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a020: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a030: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a040: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a050: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a060: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a070: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a080: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a090: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a0a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a0b0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a0c0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a0d0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0f0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a100: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a110: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a120: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a130: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a140: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a150: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a160: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a170: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f  tatements..** </
a180: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ul>.**.** <li>[[
a190: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a1a0: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a1b0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a1c0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a1d0: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a1e0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a1f0: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a200: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a210: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a220: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a230: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a240: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a250: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a260: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a270: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a280: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a290: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a2a0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a2b0: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a2c0: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a2d0: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a2e0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a2f0: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a300: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a310: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a320: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a330: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a340: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a350: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a360: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a370: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a380: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a390: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a3a0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a3b0: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a3c0: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a3d0: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a3e0: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a3f0: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a400: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a410: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a420: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
a430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
a440: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
a450: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
a460: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
a470: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a480: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
a490: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
a4a0: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a4b0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
a4c0: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a4e0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
a4f0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
a500: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
a510: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
a520: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
a530: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
a540: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
a550: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
a560: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
a570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a580: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
a590: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
a5a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a5b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a5c0: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
a5d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a5e0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
a5f0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
a600: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a610: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
a620: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
a630: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a640: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
a650: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
a660: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a670: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a680: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
a690: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a6a0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
a6b0: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
a6c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
a6d0: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
a6e0: 20 20 20 20 20 20 31 35 0a 0a 2f 2a 0a 2a 2a 20        15../*.** 
a6f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
a700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
a710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
a720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
a730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
a740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
a750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
a760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
a770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
a780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
a790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
a7a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
a7b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
a7c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
a7d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
a7e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
a7f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
a800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
a810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
a820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
a830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
a840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
a860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
a870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
a890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
a8a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
a8b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a8c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a8d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
a8e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a8f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
a900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
a910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
a920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
a930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
a940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
a950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
a960: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
a970: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
a980: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
a990: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
a9a0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
a9b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
a9c0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
a9d0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
a9e0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
a9f0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
aa00: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
aa10: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
aa20: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
aa30: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
aa40: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
aa50: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
aa60: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
aa70: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
aa80: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
aa90: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
aaa0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
aab0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
aac0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
aad0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
aae0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
aaf0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
ab00: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
ab10: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
ab20: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
ab30: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
ab40: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
ab50: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
ab60: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
ab70: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
ab80: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
ab90: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
aba0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
abb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
abc0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
abd0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
abe0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
abf0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
ac00: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
ac10: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ac20: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
ac30: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ac40: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ac50: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ac60: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ac70: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ac80: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ac90: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
aca0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
acb0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
acc0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
acd0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
ace0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
acf0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
ad00: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ad10: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ad20: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
ad30: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
ad40: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ad50: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
ad60: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
ad70: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
ad80: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
ad90: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
ada0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
adb0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
adc0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
add0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
ade0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
adf0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
ae00: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
ae10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ae20: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ae30: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
ae40: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
ae50: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
ae60: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
ae70: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
ae80: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
ae90: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
aea0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
aeb0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
aec0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
aed0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
aee0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
aef0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
af00: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
af10: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
af20: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
af30: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
af40: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
af50: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
af60: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
af70: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
af80: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
af90: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
afa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
afb0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
afc0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
afd0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
afe0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
aff0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
b000: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
b010: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
b020: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
b030: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
b040: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
b050: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
b060: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
b070: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
b080: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
b090: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
b0a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
b0b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
b0c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
b0d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
b0e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
b0f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
b100: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
b110: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
b120: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
b130: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b140: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
b150: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
b160: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
b170: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
b180: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
b190: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
b1a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
b1b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
b1c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
b1d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
b1e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
b1f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
b200: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
b210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b220: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
b230: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b240: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
b250: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
b260: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
b270: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
b280: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b290: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
b2a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b2b0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
b2c0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
b2d0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
b2e0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
b2f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
b300: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b310: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b320: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b330: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b340: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b350: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b360: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b370: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b380: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b390: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b3a0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b3b0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b3c0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b3d0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b3e0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b3f0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b400: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b410: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b420: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b430: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b440: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b450: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b460: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b470: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b480: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
b490: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b4a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
b4b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b4c0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
b4d0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b4e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
b4f0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b500: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
b510: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
b520: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b530: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
b540: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
b550: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
b560: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
b570: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
b580: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
b590: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
b5a0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
b5b0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
b5c0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
b5d0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
b5e0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
b5f0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
b600: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
b610: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
b620: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
b630: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
b640: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
b650: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
b660: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
b670: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
b680: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
b690: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
b6a0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
b6b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
b6c0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
b6d0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
b6e0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
b6f0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
b700: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
b710: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
b720: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
b730: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
b740: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
b750: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
b760: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
b770: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
b780: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
b790: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b7a0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
b7b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
b7c0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b7d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
b7e0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b7f0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
b800: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
b810: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b820: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
b830: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
b840: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
b850: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
b860: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b870: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
b880: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
b890: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
b8a0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
b8b0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
b8c0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
b8d0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
b8e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b8f0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
b900: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
b910: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
b920: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
b930: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
b940: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
b950: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
b960: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
b970: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
b980: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
b990: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
b9a0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
b9b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
b9c0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
b9d0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
b9e0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
b9f0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
ba00: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
ba10: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
ba20: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ba30: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
ba40: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
ba50: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
ba60: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
ba70: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
ba80: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
ba90: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
baa0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
bab0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
bac0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
bad0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
bae0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
baf0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
bb00: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
bb10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
bb20: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
bb30: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
bb40: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
bb50: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
bb60: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
bb70: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
bb80: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
bb90: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
bba0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
bbb0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
bbc0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
bbd0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bbe0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
bbf0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
bc00: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bc10: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
bc20: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
bc30: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
bc40: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
bc50: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
bc60: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
bc70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
bc80: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
bc90: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bca0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
bcb0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
bcc0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
bcd0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
bce0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
bcf0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
bd00: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
bd10: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
bd20: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
bd30: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
bd40: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
bd50: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
bd60: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
bd70: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
bd80: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
bd90: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
bda0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
bdb0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
bdc0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
bdd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
bde0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
bdf0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
be00: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
be10: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
be20: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
be30: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
be40: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
be50: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
be60: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
be70: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
be80: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
be90: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
bea0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
beb0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
bec0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
bed0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
bee0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
bef0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
bf00: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
bf10: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
bf20: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
bf30: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
bf40: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
bf50: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
bf60: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
bf70: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
bf80: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bf90: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
bfa0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
bfb0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
bfc0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
bfd0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
bfe0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
bff0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
c000: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
c010: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
c020: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
c030: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
c040: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
c050: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
c060: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
c070: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
c080: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
c090: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
c0a0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
c0b0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
c0c0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
c0d0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
c0e0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
c0f0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
c100: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
c110: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
c120: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
c130: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
c140: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
c150: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
c160: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
c170: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
c180: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
c190: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
c1a0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
c1b0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
c1c0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
c1d0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
c1e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
c1f0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
c200: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c210: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
c220: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
c230: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
c240: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c250: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c260: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
c270: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
c280: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
c290: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
c2a0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
c2b0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
c2c0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
c2d0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
c2e0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
c2f0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
c300: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c310: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c320: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c330: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c340: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c350: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c360: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c370: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c380: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c390: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c3a0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c3b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c3c0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c3d0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c3e0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c3f0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c400: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c410: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c420: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c430: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c440: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c450: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c460: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c470: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c480: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
c490: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
c4a0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
c4b0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
c4c0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
c4d0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
c4e0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
c4f0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
c500: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
c510: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
c520: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
c530: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
c540: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
c550: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
c560: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
c570: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
c580: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
c590: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
c5a0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
c5b0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
c5c0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
c5d0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
c5e0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
c5f0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
c600: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
c610: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
c620: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
c630: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
c640: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
c650: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
c660: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
c670: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
c680: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
c690: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
c6a0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
c6b0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
c6c0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
c6d0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
c6e0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
c6f0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
c700: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
c710: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
c720: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c730: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
c740: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
c750: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c760: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
c770: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
c780: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
c790: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
c7a0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
c7b0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
c7c0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
c7d0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
c7e0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
c7f0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
c800: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
c810: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
c820: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
c830: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
c840: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
c850: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
c860: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
c870: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
c880: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
c890: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
c8a0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
c8b0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
c8c0: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
c8d0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
c8e0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
c8f0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
c900: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
c910: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c920: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c930: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
c940: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
c950: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c960: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
c970: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
c980: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c990: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c9a0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
c9b0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
c9c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c9d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c9e0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
c9f0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
ca00: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
ca10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ca20: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ca30: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
ca40: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
ca50: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
ca60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ca70: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
ca80: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
ca90: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
caa0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
cab0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
cac0: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
cad0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
cae0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
caf0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
cb00: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
cb10: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
cb20: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
cb30: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
cb40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
cb50: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
cb60: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
cb70: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
cb80: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
cb90: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
cba0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
cbb0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
cbc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
cbd0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
cbe0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
cbf0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
cc00: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
cc10: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
cc20: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
cc30: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
cc40: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
cc50: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
cc60: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
cc70: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
cc80: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
cc90: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
cca0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
ccb0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
ccc0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ccd0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
cce0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ccf0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
cd00: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
cd10: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
cd20: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
cd30: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
cd40: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
cd50: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cd60: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cd70: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
cd80: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
cd90: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
cda0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
cdb0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
cdc0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
cdd0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
cde0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
cdf0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ce00: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ce10: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ce20: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ce30: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ce40: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ce50: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ce60: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ce70: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ce80: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ce90: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
cea0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ceb0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
cec0: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ced0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
cee0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
cef0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
cf00: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
cf10: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
cf20: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cf30: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
cf40: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
cf50: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cf60: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
cf70: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
cf80: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
cf90: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
cfa0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
cfb0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
cfc0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
cfd0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
cfe0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
cff0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
d000: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
d010: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
d020: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
d030: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
d040: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d050: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
d060: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d070: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d080: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
d090: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
d0a0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d0b0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
d0c0: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
d0d0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
d0e0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
d0f0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
d100: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
d110: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
d120: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
d130: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
d140: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
d150: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
d160: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
d170: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
d180: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
d190: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
d1a0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
d1b0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
d1c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
d1d0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d1e0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d1f0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
d200: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
d210: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d220: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
d230: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
d240: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
d250: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
d260: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
d270: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
d280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d290: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
d2a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d2c0: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
d2d0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
d2e0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
d2f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d300: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d310: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d320: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d330: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d340: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d350: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d360: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d370: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d380: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d390: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d3a0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d3b0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d3c0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d3d0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d3e0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d3f0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d400: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d410: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d420: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d430: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d440: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d450: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d460: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d470: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d480: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
d490: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d4a0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
d4b0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
d4c0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
d4d0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
d4e0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
d4f0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
d500: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
d510: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
d520: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
d530: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
d540: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
d550: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
d560: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
d570: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
d580: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
d590: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
d5a0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
d5b0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
d5c0: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d5d0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
d5e0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
d5f0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
d600: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
d610: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
d620: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d630: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
d640: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
d650: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
d660: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
d670: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
d680: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
d690: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
d6a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d6b0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
d6c0: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
d6d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d6e0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
d6f0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
d700: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
d710: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
d720: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
d730: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
d740: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
d750: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
d760: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
d770: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
d780: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
d790: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
d7a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d7b0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
d7c0: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
d7d0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
d7e0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d7f0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
d800: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d810: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
d820: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
d830: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
d840: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
d850: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
d860: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
d870: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
d880: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
d890: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
d8a0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
d8b0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
d8c0: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
d8d0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
d8e0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
d8f0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
d900: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
d910: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
d920: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
d930: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
d940: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
d950: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
d960: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
d970: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
d980: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
d990: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
d9a0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
d9b0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
d9c0: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d9d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d9e0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
d9f0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
da00: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
da10: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
da20: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
da30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
da40: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
da50: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
da60: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
da70: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
da80: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
da90: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
daa0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
dab0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
dac0: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
dad0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
dae0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
daf0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
db00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
db10: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
db20: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
db30: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
db40: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
db50: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
db60: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
db70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
db80: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
db90: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
dba0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dbb0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
dbc0: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
dbd0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
dbe0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
dbf0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
dc00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
dc10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
dc20: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dc30: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
dc40: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
dc50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dc60: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
dc70: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
dc80: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
dc90: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
dca0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
dcb0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
dcc0: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
dcd0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
dce0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
dcf0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
dd00: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
dd10: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
dd20: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
dd30: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
dd40: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
dd50: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
dd60: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
dd70: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
dd80: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
dd90: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
dda0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
ddb0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
ddc0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
ddd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
dde0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
ddf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
de00: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
de10: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
de20: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
de30: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
de40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
de50: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
de60: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
de70: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
de80: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
de90: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
dea0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
deb0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
dec0: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
ded0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
dee0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
def0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
df00: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
df10: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
df20: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
df30: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
df40: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
df50: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
df60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
df70: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
df80: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
df90: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
dfa0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
dfb0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
dfc0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
dfd0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
dfe0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
dff0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e000: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
e010: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
e020: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
e030: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
e040: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
e050: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
e060: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
e070: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
e080: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e090: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e0a0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
e0b0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
e0c0: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
e0d0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
e0e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
e0f0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
e100: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
e110: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
e120: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
e130: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e140: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
e150: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e160: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e170: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
e180: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
e190: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
e1a0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
e1b0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
e1c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e1d0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
e1e0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
e1f0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e200: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
e210: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
e220: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
e230: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
e240: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
e250: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
e260: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
e270: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e280: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
e290: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
e2a0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
e2b0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
e2c0: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
e2d0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e2e0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
e2f0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
e300: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e310: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e320: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e330: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e340: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e350: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e360: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e370: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e380: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e390: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e3a0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e3b0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e3c0: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e3d0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e3e0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e3f0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e400: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e410: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e420: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e430: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e440: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e450: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e460: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e470: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e480: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
e490: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
e4a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e4b0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
e4c0: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
e4d0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
e4e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
e4f0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
e500: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
e510: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
e520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e530: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
e540: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
e550: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
e560: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
e570: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
e580: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
e590: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e5a0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
e5b0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
e5c0: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
e5d0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
e5e0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
e5f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
e600: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e610: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e620: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
e630: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
e640: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
e650: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
e660: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
e670: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
e680: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
e690: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
e6a0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
e6b0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
e6c0: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
e6d0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
e6e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
e6f0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
e700: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
e710: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
e720: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
e730: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e740: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
e750: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
e760: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e770: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e780: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
e790: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
e7a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
e7b0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
e7c0: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
e7d0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
e7e0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
e7f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e800: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
e810: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
e820: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
e830: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
e840: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
e850: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
e860: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e870: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
e880: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e890: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
e8a0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
e8b0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
e8c0: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
e8d0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e8e0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
e8f0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
e900: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
e910: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
e920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
e930: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
e940: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
e950: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
e960: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
e970: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
e980: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
e990: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
e9a0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
e9b0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
e9c0: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
e9d0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
e9e0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
e9f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ea00: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
ea10: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
ea20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ea30: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
ea40: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
ea50: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ea60: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
ea70: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
ea80: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
ea90: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
eaa0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
eab0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
eac0: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
ead0: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
eae0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
eaf0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
eb00: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
eb10: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
eb20: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
eb30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
eb40: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
eb50: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
eb60: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
eb70: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
eb80: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
eb90: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eba0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
ebb0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
ebc0: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
ebd0: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
ebe0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
ebf0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
ec00: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
ec10: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ec20: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ec30: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
ec40: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
ec50: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
ec60: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ec70: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ec80: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
ec90: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
eca0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ecb0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ecc0: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ecd0: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
ece0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ecf0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ed00: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ed10: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
ed20: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
ed30: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
ed40: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
ed50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ed60: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ed70: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
ed80: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ed90: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
eda0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
edb0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
edc0: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
edd0: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
ede0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
edf0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
ee00: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
ee10: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
ee20: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
ee30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ee40: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
ee50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
ee60: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
ee70: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ee80: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ee90: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
eea0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
eeb0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
eec0: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
eed0: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
eee0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
eef0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
ef00: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
ef10: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
ef20: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
ef30: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
ef40: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
ef50: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
ef60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
ef70: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
ef80: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ef90: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
efa0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
efb0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
efc0: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
efd0: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
efe0: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
eff0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
f000: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
f010: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f020: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
f030: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
f040: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f050: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f060: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
f070: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
f080: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
f090: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
f0a0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
f0b0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
f0c0: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
f0d0: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
f0e0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
f0f0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
f100: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
f110: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f120: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
f130: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
f140: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
f150: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f160: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
f170: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
f180: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
f190: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
f1a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f1b0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
f1c0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
f1d0: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
f1e0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
f1f0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
f200: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
f210: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f220: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
f230: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
f240: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f250: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f260: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f270: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f280: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f290: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f2a0: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f2b0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f2c0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f2d0: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f2e0: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f2f0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f300: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f310: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f320: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f330: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f340: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f350: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f360: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f370: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f380: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f390: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f3a0: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f3b0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f3c0: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f3d0: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f3e0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f3f0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f400: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f410: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f420: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f430: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f440: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f450: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f460: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f470: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f480: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f490: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f4a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f4b0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f4c0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f4d0: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f4e0: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f4f0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f500: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f510: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f520: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f530: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f540: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f550: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f560: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f570: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f580: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f590: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f5a0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f5b0: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f5c0: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f5d0: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f5e0: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f5f0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f600: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f610: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f620: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f630: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f640: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f650: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f660: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f670: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f680: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f690: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f6a0: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f6b0: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f6c0: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f6d0: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f6e0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f6f0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f700: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f710: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f720: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f730: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f740: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f750: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f760: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f770: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f780: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f790: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f7a0: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f7b0: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f7c0: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f7d0: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f7e0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f7f0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f800: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f810: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f820: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f830: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f840: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f850: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f860: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f870: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f880: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f890: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f8a0: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f8b0: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f8c0: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f8d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f8e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f8f0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f900: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f910: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f920: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f930: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f940: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f950: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f960: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f970: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f980: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f990: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f9a0: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f9b0: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f9c0: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f9d0: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f9e0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f9f0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
fa00: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
fa10: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
fa20: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
fa30: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
fa40: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
fa50: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
fa60: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
fa70: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
fa80: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
fa90: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
faa0: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
fab0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fac0: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
fad0: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
fae0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
faf0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
fb00: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
fb10: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
fb20: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
fb30: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
fb40: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
fb50: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
fb60: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
fb70: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
fb80: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
fb90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fba0: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
fbb0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
fbc0: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
fbd0: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
fbe0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
fbf0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
fc00: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
fc10: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
fc20: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
fc30: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fc40: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
fc50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fc60: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
fc70: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
fc80: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
fc90: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
fca0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
fcb0: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
fcc0: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
fcd0: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
fce0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
fcf0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
fd00: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fd10: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fd20: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fd30: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
fd40: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fd50: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fd60: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fd70: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fd80: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fd90: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fda0: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
fdb0: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fdc0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fdd0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fde0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fdf0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
fe00: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fe10: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fe20: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fe30: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fe40: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fe50: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fe60: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fe70: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fe80: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fe90: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fea0: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
feb0: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fec0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fed0: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fee0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
fef0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
ff00: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
ff10: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
ff20: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
ff30: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
ff40: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
ff50: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
ff60: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
ff70: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
ff80: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
ff90: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
ffa0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
ffb0: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
ffc0: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
ffd0: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
ffe0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
fff0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
10000 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
10010 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
10020 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
10030 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
10040 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
10050 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10060 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10070 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
10080 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10090 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
100a0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
100b0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
100c0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
100d0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
100e0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
100f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10100 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
10110 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
10120 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10130 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10140 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10150 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10160 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10170 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
10180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10190 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
101a0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
101b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
101c0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
101d0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
101e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
101f0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
10200 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
10210 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
10220 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10230 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10240 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10250 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10260 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10270 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10280 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10290 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
102a0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
102b0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
102c0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
102d0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
102e0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
102f0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10300 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10310 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
10320 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
10330 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10340 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10350 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10360 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10370 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10380 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10390 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
103a0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
103b0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
103c0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
103d0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
103e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
103f0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10400 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10410 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10420 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10430 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10440 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10450 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10460 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10470 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10480 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10490 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
104a0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
104b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
104c0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
104d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
104e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
104f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
10500 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
10510 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10520 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
10530 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10540 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10550 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10560 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10570 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10580 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10590 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
105a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
105b0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
105c0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
105d0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
105e0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
105f0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
10600 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
10620 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10630 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
10640 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10650 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10660 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10670 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10690 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
106a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
106b0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
106c0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
106d0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
106e0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
106f0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
10700 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
10710 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
10720 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
10730 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
10740 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10750 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10760 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10770 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10780 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10790 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
107a0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
107b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
107c0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
107d0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
107e0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
107f0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
10800 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
10810 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
10820 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10830 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
10840 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10850 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10860 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10870 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10880 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10890 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
108a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
108b0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
108c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
108d0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
108e0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
108f0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
10900 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
10910 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
10920 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
10930 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
10940 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10950 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10960 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10970 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10980 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10990 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
109a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
109b0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
109c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
109d0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
109e0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
109f0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
10a00 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
10a10 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
10a20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10a30 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
10a40 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10a50 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10a60 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10a70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10a80 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10a90 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10aa0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
10ab0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
10ac0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
10ad0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10ae0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
10af0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
10b00 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
10b10 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
10b20 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10b30 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
10b40 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10b50 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10b60 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10b70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10b80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10b90 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10ba0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10bb0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
10bc0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
10bd0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10be0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10bf0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
10c00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10c10 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10c20 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10c30 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
10c40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10c50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10c60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10c70 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10c80 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10ca0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10cb0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10cc0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10cd0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10ce0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10cf0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10d00 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10d10 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10d20 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10d30 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10d40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10d50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10d60 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10d70 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10d80 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10d90 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10da0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10db0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10dc0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10dd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10df0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10e00 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10e10 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10e20 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10e30 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10e50 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10e70 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10e80 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10e90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10ea0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10eb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10ec0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10ee0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10ef0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10f00 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10f10 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10f20 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10f30 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10f40 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10f50 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10f60 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10f70 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10f80 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10f90 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10fa0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10fb0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10fc0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10fd0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10fe0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10ff0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
11000 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
11010 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
11020 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11030 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
11040 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11050 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
11060 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11070 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
11080 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
11090 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
110a0 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
110b0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
110c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
110d0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
110e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110f0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
11100 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
11110 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11120 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
11130 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
11140 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
11150 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
11160 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
11170 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
11180 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11190 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
111a0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
111b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
111c0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
111d0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
111e0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
111f0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
11200 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
11210 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
11220 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
11230 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
11240 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11250 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11260 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11270 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11280 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11290 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
112a0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
112b0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
112c0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
112d0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
112e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
112f0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
11300 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
11310 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
11320 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
11330 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11340 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11350 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11360 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11370 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11380 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11390 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
113a0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
113b0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
113c0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
113d0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
113e0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
113f0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
11400 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
11410 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
11420 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
11430 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11440 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11450 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11460 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11470 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11480 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11490 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
114a0 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
114b0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
114c0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
114d0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
114e0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
114f0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11500 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
11510 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
11520 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
11530 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
11540 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11550 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11560 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11570 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11580 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11590 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
115a0 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
115b0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
115c0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
115d0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
115e0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
115f0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
11600 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
11610 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
11620 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
11630 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11640 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11650 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11660 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11670 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11680 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
116a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
116b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
116c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
116d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
116e0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
116f0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
11700 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
11710 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
11720 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
11730 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
11740 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11750 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11760 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11770 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11780 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11790 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
117a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
117b0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
117c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
117d0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
117e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
117f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
11800 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
11810 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
11820 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
11830 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
11840 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11850 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11860 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11870 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11880 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11890 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
118a0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
118b0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
118c0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
118d0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
118e0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
118f0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
11900 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
11910 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
11920 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
11930 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
11940 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11950 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11960 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11970 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11980 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11990 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
119a0 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
119b0 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
119c0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
119d0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
119e0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
119f0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
11a00 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
11a10 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
11a20 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
11a30 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
11a40 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11a50 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11a60 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11a70 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11a80 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11a90 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11aa0 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
11ab0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
11ac0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
11ad0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
11ae0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
11af0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
11b00 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
11b10 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
11b20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11b30 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
11b40 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11b50 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11b60 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11b70 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11b80 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11b90 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11ba0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
11bb0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
11bc0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
11bd0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
11be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11bf0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
11c00 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
11c10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11c20 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11c30 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11c40 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11c50 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11c60 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11c70 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11c90 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11ca0 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
11cb0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
11cc0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
11cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11ce0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
11cf0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11d00 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11d10 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11d20 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11d30 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11d40 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11d50 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11d60 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11d70 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11d80 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11d90 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11da0 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11db0 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11dc0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11dd0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11de0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11df0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11e00 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11e10 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11e20 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11e30 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11e40 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11e50 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11e60 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11e70 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11e80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11e90 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11ea0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11eb0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11ec0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11ed0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11ee0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11ef0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11f00 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11f10 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11f20 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11f30 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11f40 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11f50 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11f60 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11f70 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11f80 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11f90 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11fa0 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11fb0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11fd0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11fe0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11ff0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
12000 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
12010 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
12020 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
12030 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
12040 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12050 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12060 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
12070 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12080 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12090 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
120a0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
120b0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
120c0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
120d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
120e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
120f0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
12100 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
12110 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
12120 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
12130 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12140 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
12150 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
12160 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12170 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12180 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12190 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
121a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
121b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
121c0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
121d0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
121e0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
121f0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
12200 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12210 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12220 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12230 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12240 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12250 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12260 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12270 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12280 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12290 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
122a0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
122b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
122c0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
122d0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
122e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
122f0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
12300 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
12310 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12320 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
12330 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
12340 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12350 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12360 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12370 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12380 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12390 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
123a0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
123b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
123c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
123d0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
123e0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
123f0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12400 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12410 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12420 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
12430 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12440 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12450 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12460 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12470 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12480 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12490 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
124a0 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
124b0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
124c0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
124d0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
124e0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
124f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
12500 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
12510 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
12530 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12540 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12550 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12560 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12570 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12580 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12590 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
125a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
125b0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
125c0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
125d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
125e0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
125f0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
12600 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
12610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
12620 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
12630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12640 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12650 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12660 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12670 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12680 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12690 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
126a0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
126b0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
126c0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
126d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
126e0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
126f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
12700 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
12710 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
12720 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
12730 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
12740 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12750 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12760 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12770 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12780 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12790 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
127a0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
127b0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
127c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
127d0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
127e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
127f0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
12800 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
12810 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
12820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
12830 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
12840 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12860 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12870 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12880 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12890 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
128a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
128b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
128c0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
128d0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
128e0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
128f0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
12900 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
12910 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
12920 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
12930 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12940 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12950 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12960 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12970 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12980 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12990 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
129a0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
129b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
129c0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
129e0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
129f0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12a00 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12a10 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12a20 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
12a30 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
12a40 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12a50 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12a60 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12a70 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12a80 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12a90 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12aa0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
12ab0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12ac0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
12ad0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
12ae0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12b00 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
12b10 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
12b20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
12b30 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
12b40 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12b50 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12b60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12b70 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12b80 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12b90 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12ba0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
12bb0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
12bc0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
12bd0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
12be0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
12bf0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
12c00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
12c10 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
12c20 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
12c30 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
12c40 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12c50 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12c60 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12c70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12c90 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12ca0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
12cb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12cc0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
12cd0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
12ce0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
12cf0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
12d00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12d10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12d20 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12d30 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12d40 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12d50 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12d60 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12d70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12d80 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12d90 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12da0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12db0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12dc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12dd0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12de0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12df0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12e00 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12e10 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12e20 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12e30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12e40 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12e50 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12e60 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12e70 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12e80 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12e90 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12ea0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12eb0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12ec0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12ed0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12ee0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12f00 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12f10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12f20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12f30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f40 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12f50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12f60 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12f70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12f80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12f90 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12fa0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12fb0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12fc0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12fd0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12fe0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12ff0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
13000 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
13010 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
13020 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
13030 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
13040 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
13050 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
13060 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
13070 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
13080 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
13090 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
130a0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
130b0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
130c0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
130d0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
130e0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
130f0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
13100 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
13110 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
13120 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
13130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
13140 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
13150 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13160 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
13170 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
13180 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
13190 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
131a0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
131b0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
131c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
131d0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
131e0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
131f0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
13200 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
13210 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
13220 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
13230 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
13240 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13250 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13260 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13270 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13280 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
13290 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
132a0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
132b0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
132c0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
132d0 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
132e0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
132f0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
13300 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
13310 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
13320 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
13330 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13340 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
13350 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
13360 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
13370 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20  optimizer.  The 
13380 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
13390 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
133a0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
133b0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
133c0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
133d0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
133e0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
133f0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
13400 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
13410 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
13420 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
13430 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
13440 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
13450 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13460 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
13470 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
13480 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
13490 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
134a0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  malfunction.** m
134b0 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20  alfunction when 
134c0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
134d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
134e0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
134f0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
13500 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
13510 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
13520 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
13530 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
13540 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
13550 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
13560 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
13570 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
13580 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13590 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
135a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
135b0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
135c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
135d0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
135e0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
135f0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
13600 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
13610 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
13620 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
13630 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
13640 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
13650 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
13660 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
13670 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
13680 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
13690 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
136a0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
136b0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
136c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
136d0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
136e0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
136f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13700 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
13710 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13730 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
13740 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
13750 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
13760 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13770 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
13780 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
13790 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
137a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
137b0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
137c0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
137d0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
137e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
137f0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
13800 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
13810 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
13820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13830 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
13840 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
13850 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
13860 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
13870 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13880 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
13890 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
138a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
138b0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
138c0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
138d0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
138e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
138f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
13900 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
13910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
13920 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
13930 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
13940 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
13950 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
13960 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
13970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13980 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
13990 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
139a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
139b0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
139c0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
139d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
139e0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
139f0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
13a00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
13a10 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
13a20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
13a30 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
13a40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13a50 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
13a60 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
13a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13a80 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
13a90 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
13aa0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
13ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13ac0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13ad0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
13ae0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13af0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
13b00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
13b10 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13b20 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
13b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13b40 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
13b50 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
13b60 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
13b70 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
13b80 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
13b90 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
13ba0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13bb0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
13bc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
13bd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13be0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
13bf0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
13c00 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13c10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13c20 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13c30 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13c40 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13c50 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13c60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c70 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13c80 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13c90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13ca0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13cb0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
13cc0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13cd0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13ce0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13cf0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
13d00 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13d10 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
13d20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
13d30 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13d40 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
13d50 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
13d60 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
13d70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
13d80 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
13d90 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
13da0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13db0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
13dc0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
13dd0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
13de0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
13df0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13e00 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
13e10 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13e20 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
13e30 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
13e40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13e50 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
13e60 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
13e70 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
13e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13e90 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
13ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
13eb0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
13ec0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
13ed0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
13ee0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13ef0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
13f00 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13f10 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
13f20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
13f30 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
13f40 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
13f50 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
13f60 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
13f70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13f80 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
13f90 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
13fa0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
13fb0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
13fc0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
13fd0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
13fe0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
13ff0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
14000 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
14010 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
14020 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
14030 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
14040 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
14050 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
14060 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
14070 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
14080 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
14090 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
140a0 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
140b0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
140c0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
140d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
140e0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
140f0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
14100 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
14110 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
14120 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
14130 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
14140 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
14150 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
14160 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
14170 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
14180 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
14190 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
141a0 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
141b0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
141c0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
141d0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
141e0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
141f0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
14200 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
14210 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
14220 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
14230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14240 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
14250 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
14260 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
14270 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
14280 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
14290 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
142a0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
142b0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
142c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
142d0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
142e0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
142f0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
14300 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
14310 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
14320 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
14330 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
14340 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
14350 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
14360 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
14370 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
14380 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
14390 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
143a0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
143b0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
143c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
143d0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
143e0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
143f0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
14400 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
14410 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
14420 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
14430 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
14440 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
14450 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
14460 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14470 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14480 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
14490 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
144a0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
144b0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
144c0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
144d0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
144e0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
144f0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
14500 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
14510 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
14520 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
14530 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
14540 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
14550 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
14560 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
14570 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14580 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
14590 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
145a0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
145b0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
145c0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
145d0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
145e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
145f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
14600 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
14610 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14620 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
14630 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
14640 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
14650 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
14660 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
14670 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
14680 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
14690 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
146a0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
146b0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
146c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
146d0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
146e0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
146f0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
14700 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
14710 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
14720 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
14730 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
14740 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14750 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
14760 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
14770 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
14780 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
14790 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
147a0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
147b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
147c0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
147d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
147e0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
147f0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
14800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
14810 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
14820 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
14830 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
14840 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
14850 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
14860 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
14870 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
14880 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
14890 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
148a0 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
148b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
148c0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
148d0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
148e0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
148f0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
14900 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
14910 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
14920 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
14930 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
14940 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
14950 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14960 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
14970 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
14980 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
14990 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
149a0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
149b0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
149c0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
149d0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
149e0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
149f0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
14a00 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
14a10 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
14a20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
14a30 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
14a40 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
14a50 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
14a60 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
14a70 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
14a80 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
14a90 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
14aa0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
14ab0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
14ac0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
14ad0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
14ae0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
14af0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
14b00 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
14b10 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
14b20 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
14b30 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
14b40 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
14b50 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
14b60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
14b70 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
14b80 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
14b90 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
14ba0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
14bb0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
14bc0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
14bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
14be0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
14bf0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
14c00 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
14c10 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
14c20 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
14c30 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
14c40 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
14c50 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
14c60 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
14c70 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
14c80 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14c90 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
14ca0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
14cb0 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
14cc0 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
14cd0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
14ce0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
14cf0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
14d00 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
14d10 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
14d20 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
14d30 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
14d40 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
14d50 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
14d60 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
14d70 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
14d80 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14d90 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
14da0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
14db0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
14dc0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14dd0 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
14de0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14df0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
14e00 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
14e10 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
14e20 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
14e30 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
14e40 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
14e50 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
14e60 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
14e70 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
14e80 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
14e90 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
14ea0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14eb0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
14ec0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
14ed0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
14ee0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
14ef0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
14f00 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
14f10 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
14f20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
14f30 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
14f40 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
14f50 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
14f60 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
14f70 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
14f80 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
14f90 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
14fa0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
14fb0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
14fc0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
14fd0 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
14fe0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
14ff0 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
15000 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
15010 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
15020 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
15030 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
15040 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
15050 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
15060 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
15070 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
15080 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
15090 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
150a0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
150b0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
150c0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
150d0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
150e0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
150f0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
15100 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
15110 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
15120 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
15130 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
15140 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
15150 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
15160 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
15170 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15180 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15190 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
151a0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
151b0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
151c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
151d0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
151e0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
151f0 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
15200 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
15210 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
15220 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
15230 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
15240 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
15250 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
15260 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
15270 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
15280 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
15290 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
152a0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
152b0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
152c0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
152d0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
152e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
152f0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
15300 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
15310 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
15320 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
15330 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
15340 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
15350 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
15360 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
15370 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
15380 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
15390 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
153a0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
153b0 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
153c0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
153d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
153e0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
153f0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
15400 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
15410 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
15420 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
15430 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
15440 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
15450 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
15460 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
15470 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
15480 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
15490 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
154a0 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
154b0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
154c0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
154d0 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
154e0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
154f0 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
15500 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
15510 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
15520 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
15530 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
15540 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
15550 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
15560 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
15570 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
15580 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
15590 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
155a0 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
155b0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
155c0 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
155d0 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
155e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
155f0 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
15600 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
15610 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
15620 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
15630 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
15640 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
15650 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
15660 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
15670 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
15680 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
15690 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
156a0 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
156b0 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
156c0 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
156d0 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
156e0 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
156f0 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
15700 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
15710 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
15720 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
15730 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
15740 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
15750 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
15760 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
15770 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
15780 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
15790 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
157a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
157b0 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
157c0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
157d0 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
157e0 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
157f0 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
15800 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
15810 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
15820 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
15830 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
15840 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
15850 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
15860 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
15870 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
15880 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
15890 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
158a0 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
158b0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
158c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
158d0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
158e0 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
158f0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
15900 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
15910 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
15920 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
15930 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15940 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
15950 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
15960 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
15970 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15980 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
15990 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
159a0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
159b0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
159c0 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
159d0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
159e0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
159f0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
15a00 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
15a10 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
15a20 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
15a30 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
15a40 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
15a50 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
15a60 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
15a70 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
15a80 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
15a90 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
15aa0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
15ab0 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
15ac0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15ad0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
15ae0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
15af0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
15b00 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15b10 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
15b20 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
15b30 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
15b40 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
15b50 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
15b60 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
15b70 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
15b80 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
15b90 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
15ba0 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
15bb0 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
15bc0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
15bd0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
15be0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
15bf0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
15c00 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
15c10 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
15c20 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
15c30 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
15c40 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
15c50 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
15c60 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
15c70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15c80 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15c90 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
15ca0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
15cb0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
15cc0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
15cd0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
15ce0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
15cf0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
15d00 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15d10 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
15d20 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15d30 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15d40 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15d50 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15d60 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
15d70 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
15d80 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
15d90 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
15da0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
15db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15dc0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
15dd0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
15de0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15df0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
15e00 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
15e10 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
15e20 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
15e30 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
15e40 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
15e50 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
15e60 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15e70 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
15e80 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
15e90 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
15ea0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
15eb0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
15ec0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
15ed0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
15ee0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
15ef0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
15f00 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
15f10 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
15f20 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
15f30 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
15f40 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
15f50 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
15f60 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
15f70 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
15f80 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
15f90 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
15fa0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
15fb0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
15fc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
15fd0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
15fe0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
15ff0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
16000 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
16010 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
16020 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
16030 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
16040 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
16050 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
16060 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
16070 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
16080 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
16090 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
160a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
160b0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
160c0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
160d0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
160e0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
160f0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
16100 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
16110 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
16120 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
16130 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
16140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
16150 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
16160 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
16170 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
16180 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
16190 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
161a0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
161b0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
161c0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
161d0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
161e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
161f0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
16200 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
16210 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
16220 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
16230 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
16240 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
16250 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
16260 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
16270 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
16280 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
16290 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
162a0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
162b0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
162c0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
162d0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
162e0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
162f0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
16300 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
16310 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
16320 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
16330 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
16340 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
16350 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
16360 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
16370 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
16380 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
16390 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
163a0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
163b0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
163c0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
163d0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
163e0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
163f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
16400 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
16410 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
16420 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
16430 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
16440 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
16450 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
16460 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
16470 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
16480 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
16490 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
164a0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
164b0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
164c0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
164d0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
164e0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
164f0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
16500 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
16510 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
16520 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
16530 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
16540 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
16550 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
16560 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
16570 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
16580 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16590 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
165a0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
165b0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
165c0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
165d0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
165e0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
165f0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
16600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
16610 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
16620 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
16630 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
16640 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
16650 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
16660 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
16670 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
16680 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
16690 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
166a0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
166b0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
166c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
166d0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
166e0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
166f0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
16700 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
16710 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
16720 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
16730 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
16740 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16750 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
16760 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
16770 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16780 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16790 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
167a0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
167b0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
167c0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
167d0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
167e0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
167f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
16800 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
16810 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
16820 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
16830 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
16840 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
16850 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
16860 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
16870 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
16880 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
16890 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
168a0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
168b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
168c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
168d0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
168e0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
168f0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
16900 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
16910 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
16920 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
16930 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16940 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
16960 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
16970 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
16980 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
16990 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
169a0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
169b0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
169c0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
169d0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
169e0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
169f0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
16a00 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16a10 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
16a20 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
16a30 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
16a40 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
16a50 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
16a60 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
16a70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16a80 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
16a90 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
16aa0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
16ab0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16ac0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
16ad0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
16ae0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
16af0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
16b00 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
16b10 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
16b20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
16b30 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
16b40 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
16b50 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
16b60 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
16b70 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
16b80 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
16b90 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
16ba0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
16bb0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
16bc0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
16bd0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
16be0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
16bf0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
16c00 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
16c10 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
16c20 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
16c30 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
16c40 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
16c50 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
16c60 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
16c70 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
16c80 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
16c90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16ca0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
16cb0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
16cc0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
16cd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
16ce0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
16cf0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
16d00 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16d10 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
16d20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
16d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16d40 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
16d50 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
16d60 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
16d70 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
16d80 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
16d90 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
16da0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
16db0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
16dc0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
16dd0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
16de0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
16df0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
16e00 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
16e10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
16e20 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
16e30 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
16e40 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
16e50 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
16e60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
16e70 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
16e80 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
16e90 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
16ea0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
16eb0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
16ec0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
16ed0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
16ee0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
16ef0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
16f00 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
16f10 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
16f20 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
16f30 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
16f40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
16f50 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
16f60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
16f70 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
16f80 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
16f90 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
16fa0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
16fb0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
16fc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16fd0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
16fe0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
16ff0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
17000 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
17010 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
17020 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
17030 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
17040 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
17050 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
17060 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
17070 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
17080 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
17090 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
170a0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
170b0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
170c0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
170d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
170e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
170f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
17100 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
17110 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
17120 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
17130 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
17140 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
17150 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
17160 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
17170 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
17180 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
17190 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
171a0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
171b0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
171c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
171d0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
171e0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
171f0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
17200 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
17210 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
17220 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
17230 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
17240 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
17250 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
17260 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
17270 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
17280 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
17290 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
172a0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
172b0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
172c0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
172d0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
172e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
172f0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
17300 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
17310 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
17320 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
17330 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
17340 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17350 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
17360 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
17370 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
17380 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
17390 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
173a0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
173b0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
173c0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
173d0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
173e0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
173f0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
17400 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
17410 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
17420 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
17430 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
17440 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
17450 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
17460 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17470 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
17480 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
17490 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
174a0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
174b0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
174c0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
174d0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
174e0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
174f0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
17500 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
17510 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
17520 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
17530 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
17540 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
17550 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
17560 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
17570 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
17580 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
17590 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
175a0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
175b0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
175c0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
175d0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
175e0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
175f0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
17600 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
17610 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
17620 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
17630 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
17640 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
17650 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
17660 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
17670 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
17680 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
17690 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
176a0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
176b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
176c0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
176d0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
176e0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
176f0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
17700 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
17710 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
17720 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
17730 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
17740 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
17750 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
17760 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
17770 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
17780 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
17790 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
177a0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
177b0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
177c0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
177d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
177e0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
177f0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
17800 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
17810 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
17820 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
17830 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
17840 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
17850 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
17860 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
17870 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
17880 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
17890 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
178a0 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
178b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
178c0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
178d0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
178e0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
178f0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
17900 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
17910 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
17920 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
17930 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
17940 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
17950 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
17960 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
17970 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
17980 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
17990 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
179a0 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
179b0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
179c0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
179d0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
179e0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
179f0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
17a00 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
17a10 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
17a20 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
17a30 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
17a40 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
17a50 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
17a60 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
17a70 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
17a80 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
17a90 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
17aa0 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
17ab0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
17ac0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
17ad0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
17ae0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
17af0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
17b00 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
17b10 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
17b20 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
17b30 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
17b40 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
17b50 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
17b60 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
17b70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17b80 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
17b90 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
17ba0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
17bb0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
17bc0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
17bd0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
17be0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
17bf0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
17c00 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
17c10 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
17c20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
17c30 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
17c40 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
17c50 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
17c60 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
17c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
17c80 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
17c90 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
17ca0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
17cb0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
17cc0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
17cd0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
17ce0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
17cf0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
17d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
17d10 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
17d20 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
17d30 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
17d40 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
17d50 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17d60 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
17d70 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
17d80 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17d90 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
17da0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
17db0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
17dc0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
17dd0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
17de0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
17df0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
17e00 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
17e10 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
17e20 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
17e30 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
17e40 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
17e50 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
17e60 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
17e70 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
17e80 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
17e90 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
17ea0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
17eb0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
17ec0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
17ed0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
17ee0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
17ef0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
17f00 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
17f10 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
17f20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17f30 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
17f40 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
17f50 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
17f60 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
17f70 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
17f80 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
17f90 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
17fa0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
17fb0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
17fc0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
17fd0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
17fe0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
17ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
18000 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
18010 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
18020 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
18030 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
18040 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
18050 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
18060 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
18070 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
18080 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
18090 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
180a0 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ed.)^.*/.int sql
180b0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
180c0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
180d0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
180e0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
180f0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
18100 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
18110 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
18120 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
18130 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
18140 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
18150 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
18160 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
18170 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
18180 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
18190 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
181a0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
181b0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
181c0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
181d0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
181e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
181f0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
18200 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
18210 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
18220 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
18230 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
18240 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
18250 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
18260 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
18270 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
18280 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
18290 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
182a0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
182b0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
182c0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
182d0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
182e0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
182f0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
18300 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
18310 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
18320 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
18330 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
18340 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18350 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
18360 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
18370 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
18380 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
18390 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
183a0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
183b0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
183c0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
183d0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
183e0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
183f0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
18400 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
18410 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
18420 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
18430 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
18440 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
18450 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
18460 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
18470 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
18480 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
18490 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
184a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
184b0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
184c0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
184d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
184e0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
184f0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
18500 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
18510 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
18520 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
18530 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
18540 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
18550 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
18560 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
18570 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
18580 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
18590 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
185a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
185b0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
185c0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
185d0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
185e0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
185f0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
18600 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
18610 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
18620 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
18630 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
18640 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
18650 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
18660 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
18670 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
18680 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
18690 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
186a0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
186b0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
186c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
186d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
186e0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
186f0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
18700 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
18710 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
18720 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
18730 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
18740 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18750 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
18760 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
18770 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
18780 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
18790 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
187a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
187b0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
187c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
187d0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
187e0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
187f0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
18800 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
18810 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
18820 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
18830 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
18840 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
18850 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
18860 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
18870 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
18880 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
18890 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
188a0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
188b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
188c0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
188d0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
188e0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
188f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
18900 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
18910 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
18920 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
18930 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
18940 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
18950 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
18960 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
18970 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
18980 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
18990 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
189a0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
189b0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
189c0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
189d0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
189e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
189f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
18a00 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
18a10 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
18a20 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
18a30 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
18a40 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
18a50 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
18a60 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
18a70 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
18a80 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
18a90 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
18aa0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
18ab0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
18ac0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
18ad0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
18ae0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
18af0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
18b00 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
18b10 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
18b20 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
18b30 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
18b40 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18b50 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
18b60 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
18b70 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
18b80 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
18b90 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18ba0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
18bb0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
18bc0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
18bd0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
18be0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
18bf0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
18c00 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
18c10 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
18c20 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
18c30 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
18c40 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
18c50 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
18c60 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
18c70 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
18c80 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
18c90 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
18ca0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
18cb0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
18cc0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
18cd0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
18ce0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
18cf0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
18d00 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
18d10 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18d20 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
18d30 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
18d40 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
18d50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
18d60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18d70 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
18d80 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
18d90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
18da0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
18db0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
18dc0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
18dd0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
18de0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
18df0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
18e00 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
18e10 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
18e20 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
18e30 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
18e40 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
18e50 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
18e60 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
18e70 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
18e80 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
18e90 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
18ea0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
18eb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
18ec0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
18ed0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
18ee0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
18ef0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
18f00 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
18f10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18f20 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
18f30 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
18f40 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
18f50 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
18f60 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
18f70 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
18f80 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
18f90 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
18fa0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
18fb0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
18fc0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
18fd0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
18fe0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
18ff0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
19000 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
19010 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
19020 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
19030 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
19040 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19050 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
19060 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
19070 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
19080 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19090 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
190a0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
190b0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
190c0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
190d0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
190e0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
190f0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
19100 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
19110 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
19120 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
19130 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
19140 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
19150 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
19160 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
19170 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19180 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
19190 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
191a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
191b0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
191c0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
191d0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
191e0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
191f0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
19200 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
19210 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
19220 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
19230 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
19240 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
19250 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
19260 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
19270 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
19280 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
19290 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
192a0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
192b0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
192c0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
192d0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
192e0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
192f0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
19300 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
19310 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
19320 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
19330 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
19340 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
19350 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
19360 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
19370 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19380 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
19390 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
193a0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
193b0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
193c0 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
193d0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
193e0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
193f0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
19400 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
19410 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
19420 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
19430 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
19440 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
19450 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
19460 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
19470 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
19480 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
19490 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
194a0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
194b0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
194c0 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
194d0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
194e0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
194f0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
19500 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
19510 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
19520 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
19530 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
19540 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
19550 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19560 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
19570 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
19580 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
19590 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
195a0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
195b0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
195c0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
195d0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
195e0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
195f0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
19600 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
19610 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
19620 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
19630 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
19640 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
19650 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
19660 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
19670 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
19680 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
19690 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
196a0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
196b0 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
196c0 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
196d0 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
196e0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
196f0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
19700 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
19710 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
19720 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
19730 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
19740 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
19750 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
19760 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
19770 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
19780 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
19790 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
197a0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
197b0 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
197c0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
197d0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
197e0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
197f0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
19800 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
19810 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
19820 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
19830 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
19840 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
19850 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
19860 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19870 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
19880 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
19890 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
198a0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
198b0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
198c0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
198d0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
198e0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
198f0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
19900 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
19910 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
19920 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
19930 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
19940 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
19950 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
19960 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
19970 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
19980 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19990 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
199a0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
199b0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
199c0 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
199d0 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
199e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
199f0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
19a00 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
19a10 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
19a20 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
19a30 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
19a40 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
19a50 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
19a60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19a70 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
19a80 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
19a90 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
19aa0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19ab0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19ac0 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
19ad0 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
19ae0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
19af0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
19b00 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
19b10 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
19b20 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
19b30 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
19b40 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
19b50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
19b60 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
19b70 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
19b80 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
19b90 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
19ba0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
19bb0 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
19bc0 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
19bd0 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
19be0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
19bf0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
19c00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
19c10 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
19c20 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
19c30 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
19c40 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
19c50 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
19c60 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
19c70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19c80 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
19c90 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
19ca0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
19cb0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
19cc0 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
19cd0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
19ce0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
19cf0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
19d00 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
19d10 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19d20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
19d30 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
19d40 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
19d50 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
19d60 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
19d70 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
19d80 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
19d90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
19da0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
19db0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
19dc0 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
19dd0 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
19de0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
19df0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
19e00 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
19e10 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
19e20 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
19e30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19e40 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
19e50 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
19e60 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
19e70 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
19e80 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
19e90 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
19ea0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
19eb0 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
19ec0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19ed0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
19ee0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
19ef0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
19f00 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
19f10 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
19f20 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
19f30 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
19f40 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
19f50 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
19f60 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
19f70 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
19f80 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
19f90 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
19fa0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
19fb0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
19fc0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
19fd0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
19fe0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
19ff0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1a000 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1a010 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1a020 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1a030 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1a040 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1a050 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1a060 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1a070 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1a080 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1a090 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1a0a0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1a0b0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1a0c0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1a0d0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1a0e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1a0f0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1a100 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1a110 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1a120 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1a130 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1a140 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1a150 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1a160 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1a170 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1a180 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1a190 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1a1a0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1a1b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1a1c0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1a1d0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1a1e0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1a1f0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1a200 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1a210 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1a220 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1a230 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1a240 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1a250 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1a260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1a270 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1a280 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1a290 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1a2a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1a2b0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1a2c0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1a2d0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1a2e0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1a2f0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1a300 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1a310 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1a320 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1a330 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1a340 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1a350 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1a360 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1a370 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1a380 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1a390 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1a3a0 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1a3b0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1a3c0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1a3d0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1a3e0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1a3f0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1a400 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1a410 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1a420 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1a430 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1a440 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1a450 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
1a460 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1a470 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
1a480 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1a490 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1a4a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1a4b0 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1a4c0 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
1a4d0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
1a4e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1a4f0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a500 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
1a510 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1a520 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
1a530 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
1a540 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a550 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1a560 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a570 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1a580 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1a590 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1a5a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1a5b0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1a5c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a5d0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1a5e0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
1a5f0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a600 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1a610 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1a620 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1a630 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1a640 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1a650 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1a660 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
1a670 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
1a680 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a690 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1a6a0 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
1a6b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1a6c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a6d0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1a6e0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1a6f0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1a700 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1a710 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1a720 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
1a730 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1a740 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1a750 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1a760 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1a770 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1a780 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1a790 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1a7a0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1a7b0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1a7c0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1a7d0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
1a7e0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1a7f0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1a800 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1a810 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
1a820 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
1a830 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1a840 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1a850 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1a860 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a870 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
1a880 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a890 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1a8a0 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1a8b0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1a8c0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1a8d0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1a8e0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1a8f0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1a900 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1a910 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1a920 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1a930 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1a940 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1a950 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1a960 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1a970 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1a980 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1a990 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1a9a0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1a9b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1a9c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a9d0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1a9e0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1a9f0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1aa00 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1aa10 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1aa20 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1aa30 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1aa40 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1aa50 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1aa60 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1aa70 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1aa80 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1aa90 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1aaa0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1aab0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1aac0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1aad0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1aae0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1aaf0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1ab00 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1ab10 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1ab20 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1ab30 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1ab40 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1ab50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ab60 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1ab70 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1ab80 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1ab90 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1aba0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1abb0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1abc0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1abd0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1abe0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1abf0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1ac00 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1ac10 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ac20 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1ac30 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1ac40 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1ac50 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1ac60 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1ac70 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1ac80 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1ac90 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1aca0 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1acb0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1acc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1acd0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1ace0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1acf0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1ad00 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1ad10 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1ad20 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1ad30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1ad40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ad50 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
1ad60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1ad70 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
1ad80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ad90 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1ada0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1adb0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1adc0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1add0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1ade0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1adf0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1ae00 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1ae10 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1ae20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1ae30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1ae40 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1ae50 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1ae60 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ae70 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1ae80 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1ae90 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1aea0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1aeb0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1aec0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1aed0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1aee0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1aef0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1af00 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1af10 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1af20 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1af30 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1af40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1af50 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1af60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1af70 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1af80 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1af90 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1afa0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1afb0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1afc0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1afd0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1afe0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1aff0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1b000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1b010 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1b020 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1b030 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1b040 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1b050 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b060 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b070 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1b080 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1b090 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1b0a0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1b0b0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1b0c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1b0d0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1b0e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1b0f0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1b100 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1b110 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1b120 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1b130 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1b140 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1b150 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1b160 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1b170 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1b180 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1b190 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1b1a0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1b1b0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1b1c0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1b1d0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1b1e0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1b1f0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1b200 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1b210 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1b220 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1b230 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1b240 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1b250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b260 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1b270 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1b280 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1b290 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1b2a0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1b2b0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1b2c0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1b2d0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1b2e0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1b2f0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1b300 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1b310 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1b320 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1b330 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1b340 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1b350 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1b360 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1b370 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1b380 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1b390 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1b3a0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1b3b0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1b3c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1b3d0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1b3e0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1b3f0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1b400 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1b410 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1b420 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1b430 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1b440 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1b450 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1b460 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1b470 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1b480 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1b490 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1b4a0 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1b4b0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1b4c0 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1b4d0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1b4e0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1b4f0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b500 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1b510 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1b520 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1b530 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1b540 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1b550 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1b560 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1b570 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1b580 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1b590 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1b5a0 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1b5b0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1b5c0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1b5d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b5e0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1b5f0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1b600 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1b610 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1b620 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1b630 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1b640 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b650 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b660 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1b670 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1b680 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1b690 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b6a0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1b6b0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1b6c0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1b6d0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1b6e0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b6f0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1b700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b710 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1b720 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1b730 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1b740 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1b750 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1b760 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1b770 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1b780 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1b790 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1b7a0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1b7b0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1b7c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b7d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1b7e0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1b7f0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1b800 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1b810 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b820 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1b830 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1b840 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1b850 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1b860 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1b870 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1b880 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1b890 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b8a0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1b8b0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1b8c0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1b8d0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1b8e0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1b8f0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1b900 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1b910 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1b920 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b930 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1b940 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1b950 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1b960 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1b970 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1b980 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1b990 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b9a0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1b9b0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1b9c0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1b9d0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1b9e0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b9f0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1ba00 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1ba10 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1ba20 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1ba30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1ba40 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1ba50 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1ba60 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ba70 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1ba80 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1ba90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1baa0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1bab0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1bac0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1bad0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1bae0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1baf0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1bb00 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1bb10 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1bb20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1bb30 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1bb40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1bb50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1bb60 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1bb70 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1bb80 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bb90 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1bba0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1bbb0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1bbc0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1bbd0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1bbe0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1bbf0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1bc00 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1bc10 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1bc20 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1bc30 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1bc40 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1bc50 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1bc60 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1bc70 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1bc80 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1bc90 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1bca0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1bcb0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1bcc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1bcd0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1bce0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1bcf0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1bd00 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bd10 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1bd20 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1bd30 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1bd40 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1bd50 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1bd60 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1bd70 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1bd80 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1bd90 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1bda0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1bdb0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1bdc0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1bdd0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1bde0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1bdf0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1be00 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1be10 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1be20 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1be30 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1be40 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1be50 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1be60 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1be70 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1be80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1be90 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1bea0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1beb0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1bec0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1bed0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1bee0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1bef0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1bf00 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1bf10 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1bf20 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1bf30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1bf40 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1bf50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bf60 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1bf70 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1bf80 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1bf90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1bfa0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1bfb0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1bfc0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1bfd0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1bfe0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1bff0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1c000 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1c010 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1c020 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1c030 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1c040 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1c050 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1c060 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1c070 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1c080 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1c090 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1c0a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c0b0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1c0c0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1c0d0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1c0e0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1c0f0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1c100 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1c110 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1c120 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1c130 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1c140 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1c150 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1c160 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1c170 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1c180 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1c190 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1c1a0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1c1b0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1c1c0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1c1d0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1c1e0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1c1f0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1c200 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1c210 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1c220 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1c230 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1c240 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1c250 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1c260 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1c270 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1c280 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1c290 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1c2a0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1c2b0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1c2c0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1c2d0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1c2e0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1c2f0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1c300 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1c310 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1c320 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1c330 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1c340 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1c350 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1c360 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1c370 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1c380 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1c390 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1c3a0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1c3b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1c3c0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1c3d0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1c3e0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1c3f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c400 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c410 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c420 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1c430 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1c440 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1c450 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1c460 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1c470 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c480 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1c490 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1c4a0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1c4b0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1c4c0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c4d0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1c4e0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1c4f0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1c500 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1c510 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1c520 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1c530 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1c540 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1c550 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1c560 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1c570 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1c580 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1c590 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c5a0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1c5b0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1c5c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c5d0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1c5e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c5f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c600 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1c610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c620 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c630 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1c640 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1c650 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1c660 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1c670 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1c680 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1c690 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1c6a0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1c6b0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1c6c0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1c6d0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1c6e0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1c6f0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1c700 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1c710 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
1c720 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1c730 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1c740 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1c750 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1c760 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1c770 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c780 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1c790 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1c7a0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1c7b0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1c7c0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1c7d0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1c7e0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1c7f0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1c800 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1c810 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1c820 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1c830 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1c840 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1c850 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1c860 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1c870 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1c880 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1c890 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1c8a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1c8b0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1c8c0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1c8d0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1c8e0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1c8f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1c900 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1c910 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1c920 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1c930 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1c940 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1c950 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1c960 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1c970 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1c980 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1c990 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1c9a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c9b0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1c9c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c9d0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1c9e0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1c9f0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1ca00 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1ca10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ca20 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1ca30 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1ca40 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1ca50 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1ca60 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1ca70 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1ca80 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1ca90 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1caa0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1cab0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1cac0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1cad0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1cae0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1caf0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1cb00 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1cb10 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1cb20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1cb30 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1cb40 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1cb50 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1cb60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1cb70 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1cb80 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1cb90 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1cba0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1cbb0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1cbc0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1cbd0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1cbe0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1cbf0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1cc00 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1cc10 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1cc20 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1cc30 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1cc40 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1cc50 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1cc60 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1cc70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1cc80 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1cc90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1cca0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1ccb0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1ccc0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1ccd0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1cce0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1ccf0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1cd00 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1cd10 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1cd20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1cd30 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1cd40 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1cd50 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1cd60 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1cd70 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1cd80 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1cd90 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1cda0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1cdb0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1cdc0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1cdd0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1cde0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cdf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ce00 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1ce10 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1ce20 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1ce30 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1ce40 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1ce50 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1ce60 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ce70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ce80 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1ce90 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1cea0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ceb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1cec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ced0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1cee0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1cef0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cf00 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1cf10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cf20 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1cf30 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1cf40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1cf50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cf60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cf70 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1cf80 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1cf90 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1cfa0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cfb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cfc0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1cfd0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1cfe0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1cff0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d000 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d010 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1d020 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1d030 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1d040 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d060 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1d070 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1d080 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1d090 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d0a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1d0b0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1d0c0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1d0d0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d0e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d0f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d100 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1d110 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1d120 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1d130 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d140 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d150 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1d160 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1d170 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d180 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d190 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d1a0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1d1b0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1d1c0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1d1d0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d1e0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1d1f0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1d200 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d210 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d220 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d230 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1d240 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1d250 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1d260 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1d270 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d280 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1d290 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1d2a0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1d2b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d2c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d2d0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1d2e0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1d2f0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1d300 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d310 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d320 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1d330 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1d340 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1d350 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d360 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d370 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1d380 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1d390 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d3a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d3b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d3c0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1d3d0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1d3e0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1d3f0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1d400 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d410 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1d420 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1d430 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1d440 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1d450 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d460 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1d470 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1d480 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1d490 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d4a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d4b0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1d4c0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1d4d0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1d4e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d4f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1d500 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1d510 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1d520 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1d530 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1d540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1d550 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1d560 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1d570 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1d580 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1d5a0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1d5b0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1d5c0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1d5d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d5e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1d5f0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1d600 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1d610 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1d620 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d630 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1d640 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1d650 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1d660 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d670 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d680 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1d690 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1d6a0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1d6b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d6c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d6d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d6e0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1d6f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d700 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1d710 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1d720 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1d730 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1d740 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d750 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1d760 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d770 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1d780 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1d790 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1d7a0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1d7b0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1d7c0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1d7d0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1d7e0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1d7f0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1d800 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1d810 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1d820 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1d830 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1d840 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1d850 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1d860 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1d870 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1d880 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1d890 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1d8a0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1d8b0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1d8c0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1d8d0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1d8e0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1d8f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1d900 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d910 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1d920 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d930 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1d940 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1d950 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1d960 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1d970 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1d980 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1d990 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1d9a0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d9b0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1d9c0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1d9d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d9e0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1d9f0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1da00 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1da10 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1da20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1da30 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1da40 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1da50 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1da60 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1da70 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1da80 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1da90 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1daa0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1dab0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1dac0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1dad0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1dae0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1daf0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1db00 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1db10 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1db20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1db30 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1db40 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1db50 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1db60 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1db70 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1db80 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1db90 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1dba0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1dbb0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1dbc0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1dbd0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1dbe0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1dbf0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1dc00 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1dc10 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1dc20 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1dc30 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1dc40 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1dc50 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1dc60 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1dc70 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1dc80 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1dc90 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1dca0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1dcb0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1dcc0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1dcd0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1dce0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1dcf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1dd00 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1dd10 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1dd20 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1dd30 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1dd40 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1dd50 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1dd60 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
1dd70 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1dd80 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1dd90 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1dda0 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1ddb0 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1ddc0 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1ddd0 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1dde0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1ddf0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1de00 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1de10 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1de20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1de30 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1de40 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1de50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1de60 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1de70 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1de80 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1de90 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1dea0 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1deb0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1dec0 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1ded0 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1dee0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1def0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1df00 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1df10 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1df20 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1df30 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1df40 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1df50 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1df60 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1df70 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1df80 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1df90 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1dfa0 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1dfb0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1dfc0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1dfd0 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1dfe0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1dff0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1e000 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1e010 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1e020 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1e030 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1e040 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1e050 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1e060 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1e070 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1e080 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1e090 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e0a0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1e0b0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1e0c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e0d0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1e0e0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1e0f0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1e100 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1e110 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1e120 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1e130 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1e140 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1e150 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1e160 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1e170 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1e180 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1e190 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1e1a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1e1b0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1e1c0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1e1d0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1e1e0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1e1f0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1e200 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1e210 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1e220 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1e230 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1e240 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1e250 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1e260 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1e270 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e280 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e290 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e2a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e2b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e2c0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1e2d0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1e2e0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1e2f0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1e300 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1e310 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1e320 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1e330 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1e340 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1e350 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1e360 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1e370 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1e380 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1e390 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1e3a0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1e3b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e3c0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1e3d0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e3e0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1e3f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1e400 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1e410 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1e420 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1e430 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1e440 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1e450 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1e460 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1e470 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1e480 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1e490 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1e4a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1e4b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1e4c0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1e4d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1e4e0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1e4f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1e500 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1e510 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1e520 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1e530 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1e540 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1e550 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1e560 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1e570 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1e580 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1e590 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1e5a0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1e5b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1e5c0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1e5d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1e5e0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1e5f0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1e600 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e610 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1e620 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1e630 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1e640 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1e650 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1e660 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1e670 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1e680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1e690 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1e6a0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1e6b0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1e6c0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1e6d0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1e6e0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1e6f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1e700 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1e710 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1e720 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1e730 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1e740 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1e750 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1e760 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1e770 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1e780 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1e790 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e7a0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1e7b0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e7c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e7d0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1e7e0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1e7f0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1e800 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1e810 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1e820 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1e830 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1e840 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1e850 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1e860 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1e870 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1e880 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1e890 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1e8a0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1e8b0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1e8c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1e8d0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1e8e0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1e8f0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1e900 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1e910 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1e920 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1e930 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1e940 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1e950 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1e960 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1e970 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1e980 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1e990 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1e9a0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1e9b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1e9c0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1e9d0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1e9e0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1e9f0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1ea00 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1ea10 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1ea20 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1ea30 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
1ea40 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1ea50 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
1ea60 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ea70 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1ea80 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1ea90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1eaa0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1eab0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1eac0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1ead0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1eae0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1eaf0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1eb00 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1eb10 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1eb20 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1eb30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1eb40 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1eb50 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1eb60 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1eb70 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1eb80 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1eb90 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1eba0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1ebb0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1ebc0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1ebd0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1ebe0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1ebf0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1ec00 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1ec10 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1ec20 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1ec30 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1ec40 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ec50 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1ec60 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1ec70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1ec80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1ec90 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1eca0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1ecb0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1ecc0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1ecd0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1ece0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1ecf0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1ed00 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1ed10 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ed20 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1ed30 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1ed40 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1ed50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ed60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ed70 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1ed80 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1ed90 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
1eda0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1edb0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
1edc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1edd0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
1ede0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
1edf0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1ee00 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1ee10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
1ee20 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1ee30 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1ee40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ee50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1ee60 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
1ee70 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
1ee80 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
1ee90 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
1eea0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
1eeb0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
1eec0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1eed0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
1eee0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
1eef0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1ef00 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1ef10 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ef20 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1ef30 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1ef40 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1ef50 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1ef60 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1ef70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ef80 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1ef90 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1efa0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
1efb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1efc0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
1efd0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1efe0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1eff0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
1f000 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
1f010 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
1f020 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1f030 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
1f040 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1f050 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f060 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1f070 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
1f080 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f090 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1f0a0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1f0b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f0c0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
1f0d0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
1f0e0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
1f0f0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
1f100 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1f110 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f130 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1f140 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1f150 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1f160 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1f170 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1f180 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1f190 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1f1a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f1b0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1f1c0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1f1d0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1f1e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1f1f0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1f200 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1f210 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1f220 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1f230 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1f240 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1f250 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1f260 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1f270 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1f280 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1f290 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1f2a0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1f2b0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1f2c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f2d0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1f2e0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1f2f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1f300 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1f310 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1f320 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1f330 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1f340 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1f350 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1f360 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1f370 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1f380 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1f390 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1f3a0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1f3b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1f3c0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1f3d0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1f3e0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1f3f0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1f400 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1f410 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1f420 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1f430 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1f440 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1f450 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1f460 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1f470 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1f480 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1f490 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1f4a0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1f4b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1f4c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1f4d0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
1f4e0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
1f4f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
1f500 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
1f510 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
1f520 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
1f530 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1f540 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
1f550 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f560 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
1f570 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
1f580 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1f590 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f5a0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
1f5b0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1f5c0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1f5d0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
1f5e0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
1f5f0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
1f600 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1f610 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f620 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
1f630 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
1f640 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
1f650 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
1f660 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
1f670 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
1f680 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1f690 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
1f6a0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
1f6b0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
1f6c0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
1f6d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1f6e0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
1f6f0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1f700 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
1f710 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
1f720 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
1f730 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
1f740 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
1f750 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
1f760 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
1f770 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
1f780 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
1f790 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1f7a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1f7b0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
1f7c0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
1f7d0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
1f7e0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
1f7f0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
1f800 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
1f810 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
1f820 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1f830 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
1f840 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
1f850 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
1f860 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
1f870 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
1f880 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
1f890 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1f8a0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
1f8b0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
1f8c0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
1f8d0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
1f8e0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
1f8f0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
1f900 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
1f910 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
1f920 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f930 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
1f940 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
1f950 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
1f960 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
1f970 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
1f980 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
1f990 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1f9a0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
1f9b0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
1f9c0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
1f9d0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
1f9e0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
1f9f0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
1fa00 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
1fa10 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
1fa20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
1fa30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fa40 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
1fa50 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
1fa60 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
1fa70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
1fa80 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
1fa90 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
1faa0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
1fab0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
1fac0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
1fad0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
1fae0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1faf0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
1fb00 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
1fb10 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
1fb20 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
1fb30 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
1fb40 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
1fb50 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
1fb60 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
1fb70 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
1fb80 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1fb90 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
1fba0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
1fbb0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
1fbc0 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
1fbd0 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
1fbe0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
1fbf0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
1fc00 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
1fc10 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
1fc20 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1fc30 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1fc40 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
1fc50 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
1fc60 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1fc70 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
1fc80 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
1fc90 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
1fca0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1fcb0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
1fcc0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1fcd0 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
1fce0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
1fcf0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
1fd00 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1fd10 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
1fd20 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
1fd30 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
1fd40 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
1fd50 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1fd60 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
1fd70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
1fd80 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
1fd90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
1fda0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1fdb0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fdc0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
1fdd0 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
1fde0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
1fdf0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1fe00 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
1fe10 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
1fe20 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
1fe30 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
1fe40 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
1fe50 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
1fe60 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
1fe70 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
1fe80 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
1fe90 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1fea0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1feb0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
1fec0 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
1fed0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1fee0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
1fef0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
1ff00 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
1ff10 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1ff20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1ff30 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1ff40 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1ff50 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1ff60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ff70 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1ff80 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1ff90 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1ffa0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1ffb0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1ffc0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1ffd0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1ffe0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1fff0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
20000 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
20010 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
20020 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
20030 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20040 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
20050 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
20060 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
20070 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
20080 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
20090 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
200a0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
200b0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
200c0 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
200d0 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
200e0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
200f0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
20100 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
20110 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
20120 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
20130 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
20140 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
20150 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
20160 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
20170 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
20180 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20190 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
201a0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
201b0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
201c0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
201d0 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
201e0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
201f0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
20200 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
20210 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
20220 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
20230 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
20240 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
20250 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
20260 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
20270 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
20280 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
20290 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
202a0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
202b0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
202c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
202d0 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
202e0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
202f0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
20300 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
20310 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
20320 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
20330 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
20340 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
20350 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
20360 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
20370 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
20380 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
20390 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
203a0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
203b0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
203c0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
203d0 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
203e0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
203f0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
20400 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
20410 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
20420 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
20430 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
20440 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20450 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
20460 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
20470 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
20480 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
20490 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
204a0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
204b0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
204c0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
204d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
204e0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
204f0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
20500 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
20510 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
20520 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
20530 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
20540 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
20550 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
20560 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
20570 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
20580 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
20590 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
205a0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
205b0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
205c0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
205d0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
205e0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
205f0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
20600 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
20610 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
20620 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
20630 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
20640 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
20650 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
20660 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
20670 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
20680 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20690 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
206a0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
206b0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
206c0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
206d0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
206e0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
206f0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
20700 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
20710 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
20720 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
20730 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
20740 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
20750 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
20760 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
20770 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
20780 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
20790 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
207a0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
207b0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
207c0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
207d0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
207e0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
207f0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
20800 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
20810 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
20820 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
20830 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
20840 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
20850 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
20860 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
20870 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
20880 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
20890 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
208a0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
208b0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
208c0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
208d0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
208e0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
208f0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
20900 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
20910 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
20920 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
20930 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
20940 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
20950 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
20960 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
20970 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
20980 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
20990 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
209a0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
209b0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
209c0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
209d0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
209e0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
209f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20a00 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
20a10 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
20a20 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
20a30 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
20a40 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
20a50 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
20a60 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
20a70 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
20a80 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
20a90 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20aa0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
20ab0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
20ac0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
20ad0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
20ae0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
20af0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20b00 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
20b10 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
20b20 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
20b30 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
20b40 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
20b50 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
20b60 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
20b70 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
20b80 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
20b90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
20ba0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
20bb0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
20bc0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
20bd0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
20be0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
20bf0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20c00 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
20c10 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
20c20 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
20c30 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
20c40 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
20c50 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
20c60 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
20c70 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
20c80 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
20c90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
20ca0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
20cb0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
20cc0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
20cd0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
20ce0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
20cf0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
20d00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
20d10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
20d20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
20d30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
20d40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
20d50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
20d60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
20d70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
20d80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
20d90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
20da0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
20db0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
20dc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20dd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
20de0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
20df0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
20e00 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
20e10 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
20e20 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
20e30 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
20e40 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
20e50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
20e60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20e70 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
20e80 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
20e90 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
20ea0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
20eb0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
20ec0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
20ed0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
20ee0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
20ef0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
20f00 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
20f10 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
20f20 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
20f30 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
20f40 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
20f50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
20f60 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
20f70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20f80 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
20f90 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
20fa0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
20fb0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
20fc0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20fd0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
20fe0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20ff0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
21000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21010 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
21020 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
21030 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21040 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
21050 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
21060 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
21070 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
21080 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
21090 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
210a0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
210b0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
210c0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
210d0 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
210e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
210f0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
21100 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
21110 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
21120 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
21130 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
21140 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
21150 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
21160 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
21170 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
21180 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
21190 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
211a0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
211b0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
211c0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
211d0 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
211e0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
211f0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
21200 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21210 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
21220 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
21230 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
21240 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
21250 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
21260 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
21270 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
21280 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
21290 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
212a0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
212b0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
212c0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
212d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
212e0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
212f0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
21300 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
21310 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
21320 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
21330 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
21340 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
21350 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
21360 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
21370 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
21380 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
21390 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
213a0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
213b0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
213c0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
213d0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
213e0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
213f0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
21400 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
21410 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
21420 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21430 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
21440 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
21450 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
21460 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
21470 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21480 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
21490 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
214a0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
214b0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
214c0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
214d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
214e0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
214f0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
21500 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
21510 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
21520 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
21530 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
21540 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
21550 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
21560 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
21570 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
21580 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21590 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
215a0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
215b0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
215c0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
215d0 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
215e0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
215f0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
21600 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
21610 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
21620 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
21630 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
21640 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
21650 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
21660 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
21670 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
21680 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
21690 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
216a0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
216b0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
216c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
216d0 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
216e0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
216f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
21700 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
21710 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
21720 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
21730 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
21740 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
21750 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
21760 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
21770 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
21780 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
21790 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
217a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
217b0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
217c0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
217d0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
217e0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
217f0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
21800 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
21810 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
21820 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
21830 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
21840 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
21850 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
21860 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
21870 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
21880 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
21890 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
218a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
218b0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
218c0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
218d0 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
218e0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
218f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21900 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
21910 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
21920 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
21930 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
21940 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21950 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
21960 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
21970 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
21980 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
21990 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
219a0 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
219b0 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
219c0 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
219d0 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
219e0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
219f0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
21a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21a10 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
21a20 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
21a30 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
21a40 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
21a50 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21a60 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
21a70 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
21a80 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
21a90 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
21aa0 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
21ab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
21ac0 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
21ad0 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
21ae0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21af0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
21b00 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
21b10 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
21b20 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
21b30 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
21b40 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
21b50 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
21b60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
21b70 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
21b80 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
21b90 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
21ba0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21bb0 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
21bc0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21bd0 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
21be0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
21bf0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
21c00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
21c10 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
21c20 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
21c30 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
21c40 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21c50 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
21c60 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
21c70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
21c80 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21c90 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
21ca0 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
21cb0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
21cc0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
21cd0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
21ce0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
21cf0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
21d00 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
21d10 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
21d20 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
21d30 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
21d40 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
21d50 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
21d60 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
21d70 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
21d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21d90 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
21da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21db0 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
21dc0 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
21dd0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
21de0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
21df0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
21e00 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21e10 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
21e20 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
21e30 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
21e40 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
21e50 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
21e60 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
21e70 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
21e80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
21e90 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
21ea0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
21eb0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
21ec0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
21ed0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
21ee0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
21ef0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
21f00 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
21f10 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
21f20 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
21f30 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
21f40 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
21f50 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
21f60 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
21f70 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
21f80 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
21f90 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
21fa0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
21fb0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
21fc0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
21fd0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
21fe0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
21ff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22000 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
22010 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
22020 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
22030 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
22040 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
22050 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
22060 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
22070 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
22080 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
22090 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
220a0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
220b0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
220c0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
220d0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
220e0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
220f0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
22100 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
22110 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
22120 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
22130 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
22140 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
22150 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
22160 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
22170 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
22180 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
22190 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
221a0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
221b0 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
221c0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
221d0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
221e0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
221f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
22200 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
22210 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
22220 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
22230 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22240 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
22250 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22260 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
22270 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
22280 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
22290 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
222a0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
222b0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
222c0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
222d0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
222e0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
222f0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
22300 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
22310 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
22320 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
22330 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
22340 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
22350 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
22360 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
22370 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
22380 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
22390 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
223a0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
223b0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
223c0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
223d0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
223e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
223f0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
22400 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
22410 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
22420 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
22430 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
22440 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
22450 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
22460 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
22470 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
22480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
22490 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
224a0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
224b0 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
224c0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
224d0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
224e0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
224f0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
22500 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
22510 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
22520 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
22530 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
22540 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
22550 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
22560 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
22570 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
22580 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
22590 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
225a0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
225b0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
225c0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
225d0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
225e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
225f0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
22600 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
22610 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
22620 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
22630 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
22640 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
22650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
22660 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
22670 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
22680 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
22690 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
226a0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
226b0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
226c0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
226d0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
226e0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
226f0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
22700 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
22710 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
22720 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
22730 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
22740 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22750 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
22760 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
22770 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
22780 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
22790 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
227a0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
227b0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
227c0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
227d0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
227e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
227f0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
22800 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
22810 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
22820 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
22830 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
22840 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
22850 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
22860 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
22870 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
22880 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
22890 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
228a0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
228b0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
228c0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
228d0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
228e0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
228f0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
22900 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
22910 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
22920 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
22930 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
22940 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22950 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
22960 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
22970 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
22980 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22990 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
229a0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
229b0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
229c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
229d0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
229e0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
229f0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
22a00 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
22a10 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
22a20 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
22a30 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
22a40 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
22a50 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
22a60 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
22a70 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
22a80 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
22a90 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
22aa0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
22ab0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
22ac0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
22ad0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
22ae0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
22af0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
22b00 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
22b10 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
22b20 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
22b30 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
22b40 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
22b50 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
22b60 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
22b70 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
22b80 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
22b90 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
22ba0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
22bb0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
22bc0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
22bd0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
22be0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
22bf0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
22c00 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
22c10 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
22c20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
22c30 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
22c40 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
22c50 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
22c60 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
22c70 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
22c80 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
22c90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
22ca0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
22cb0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
22cc0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
22cd0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
22ce0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
22cf0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
22d00 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
22d10 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
22d20 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
22d30 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
22d40 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
22d50 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
22d60 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
22d70 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
22d80 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
22d90 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
22da0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
22db0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
22dc0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
22dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
22de0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
22df0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
22e00 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
22e10 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
22e20 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
22e30 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
22e40 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
22e50 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
22e60 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
22e70 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
22e80 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
22e90 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
22ea0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
22eb0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
22ec0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
22ed0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
22ee0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
22ef0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
22f00 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
22f10 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
22f20 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
22f30 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
22f40 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
22f50 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22f60 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
22f70 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22f80 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
22f90 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
22fa0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
22fb0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
22fc0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22fd0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
22fe0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22ff0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
23000 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23010 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
23020 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
23030 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
23040 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23050 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
23060 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23070 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
23080 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23090 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
230a0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
230b0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
230c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
230d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
230e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
230f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
23100 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
23110 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
23120 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
23130 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
23140 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23150 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
23160 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23170 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
23180 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23190 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
231a0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
231b0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
231c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
231d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
231e0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
231f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
23200 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
23210 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23220 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
23230 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
23240 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
23250 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
23260 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23270 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
23280 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23290 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
232a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
232b0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
232c0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
232d0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
232e0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
232f0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
23300 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
23310 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
23320 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
23330 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
23340 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
23350 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
23360 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
23370 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
23380 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23390 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
233a0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
233b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
233c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
233d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
233e0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
233f0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
23400 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23410 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
23420 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23430 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
23440 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23450 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23460 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
23470 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
23480 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
23490 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
234a0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
234b0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
234c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
234d0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
234e0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
234f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
23500 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
23510 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
23520 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
23530 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
23540 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23550 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23560 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
23570 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23580 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
23590 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
235a0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
235b0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
235c0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
235d0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
235e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
235f0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
23600 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23610 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
23620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23630 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
23640 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
23650 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
23660 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
23670 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23680 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
23690 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
236a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
236b0 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
236c0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
236d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
236e0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
236f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
23700 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23710 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
23720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
23730 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23740 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
23750 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
23760 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
23770 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
23780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23790 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
237a0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
237b0 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
237c0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
237d0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
237e0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
237f0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
23800 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
23810 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
23820 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
23830 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
23840 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
23850 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
23860 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23870 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
23880 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
23890 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
238a0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
238b0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
238c0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
238d0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
238e0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
238f0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
23900 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
23910 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
23920 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
23930 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
23940 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
23950 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
23960 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
23970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23980 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
23990 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
239a0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
239b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
239c0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
239d0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
239e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
239f0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
23a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
23a10 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
23a20 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
23a30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
23a40 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
23a50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
23a60 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
23a70 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
23a80 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
23a90 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
23aa0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
23ab0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23ac0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
23ad0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
23ae0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
23af0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
23b00 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
23b10 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
23b20 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
23b30 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
23b40 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
23b50 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
23b60 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
23b70 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23b80 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
23b90 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
23ba0 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
23bb0 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
23bc0 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
23bd0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
23be0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23bf0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
23c00 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
23c10 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
23c20 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
23c30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
23c40 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
23c50 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
23c60 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
23c70 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
23c80 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
23c90 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
23ca0 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
23cb0 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
23cc0 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
23cd0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
23ce0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
23cf0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
23d00 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
23d10 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
23d20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23d30 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
23d40 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
23d50 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
23d60 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
23d70 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
23d80 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
23d90 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
23da0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
23db0 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
23dc0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
23dd0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
23de0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
23df0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
23e00 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
23e10 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
23e20 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
23e30 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
23e40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
23e50 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
23e60 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
23e70 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
23e80 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
23e90 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
23ea0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
23eb0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
23ec0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
23ed0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
23ee0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
23ef0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
23f00 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
23f10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23f20 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
23f30 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
23f40 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
23f50 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
23f60 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
23f70 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
23f80 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
23f90 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
23fa0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
23fb0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
23fc0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
23fd0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
23fe0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
23ff0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
24000 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
24010 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
24020 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24030 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
24040 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
24050 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
24060 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
24070 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
24080 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
24090 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
240a0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
240b0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
240c0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
240d0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
240e0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
240f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
24100 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
24110 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
24120 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
24130 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
24140 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
24150 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
24160 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
24170 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
24180 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
24190 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
241a0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
241b0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
241c0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
241d0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
241e0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
241f0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
24200 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
24210 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
24220 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
24230 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
24240 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
24250 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
24260 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
24270 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
24280 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
24290 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
242a0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
242b0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
242c0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
242d0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
242e0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
242f0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
24300 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
24310 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
24320 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
24330 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
24340 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
24350 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
24360 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
24370 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
24380 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
24390 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
243a0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
243b0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
243c0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
243d0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
243e0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
243f0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
24400 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
24410 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
24420 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
24430 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
24440 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
24450 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
24460 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
24470 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
24480 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
24490 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
244a0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
244b0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
244c0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
244d0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
244e0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
244f0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
24500 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
24510 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
24520 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
24530 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
24540 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
24550 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
24560 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
24570 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
24580 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
24590 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
245a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
245b0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
245c0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
245d0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
245e0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
245f0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
24600 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
24610 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
24620 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
24630 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
24640 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
24650 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
24660 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
24670 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
24680 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
24690 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
246a0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
246b0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
246c0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
246d0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
246e0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
246f0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
24700 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
24710 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
24720 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
24730 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
24740 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
24750 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
24760 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
24770 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
24780 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
24790 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
247a0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
247b0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
247c0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
247d0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
247e0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
247f0 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
24800 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
24810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
24820 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
24830 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24840 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24850 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24860 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
24870 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
24880 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
24890 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
248a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
248b0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
248c0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
248d0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
248e0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
248f0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
24900 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
24910 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
24920 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
24930 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
24940 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
24950 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
24960 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
24970 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
24980 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
24990 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
249a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
249b0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
249c0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
249d0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
249e0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
249f0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
24a00 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
24a10 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
24a20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
24a30 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24a40 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
24a50 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
24a60 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
24a70 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
24a80 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
24a90 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
24aa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24ab0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
24ac0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
24ad0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
24ae0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
24af0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
24b00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
24b10 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
24b20 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
24b30 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
24b40 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24b50 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
24b60 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
24b70 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
24b80 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
24b90 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24ba0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
24bb0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
24bc0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
24bd0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
24be0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
24bf0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
24c00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24c10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24c20 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24c30 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
24c40 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24c50 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
24c60 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24c70 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24c80 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24c90 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24ca0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24cb0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24cc0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24cd0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24ce0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
24cf0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24d00 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24d10 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24d20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
24d30 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
24d40 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
24d50 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
24d60 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
24d70 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
24d80 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
24d90 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
24da0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
24db0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
24dc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24dd0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
24de0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
24df0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
24e00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24e10 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
24e20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
24e30 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
24e40 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
24e50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24e60 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24e70 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
24e80 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
24e90 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
24ea0 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
24eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
24ec0 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
24ed0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24ee0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24ef0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
24f00 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24f10 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
24f20 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
24f30 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
24f40 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24f50 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
24f60 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
24f70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
24f90 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
24fa0 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
24fb0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
24fc0 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
24fd0 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
24fe0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
24ff0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
25000 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
25010 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
25020 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
25030 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
25040 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
25050 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
25060 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
25070 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
25080 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
25090 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
250a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
250b0 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
250c0 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
250d0 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
250e0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
250f0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
25100 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
25110 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
25120 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
25130 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25140 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
25150 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
25160 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
25170 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
25180 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
25190 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
251a0 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
251b0 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
251c0 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
251d0 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
251e0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
251f0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
25200 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
25210 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
25220 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
25230 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
25240 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
25250 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
25260 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
25270 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
25280 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
25290 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
252a0 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
252b0 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
252c0 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
252d0 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
252e0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
252f0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
25300 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
25310 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
25320 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
25330 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
25340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
25350 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
25360 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
25370 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
25380 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
25390 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
253a0 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
253b0 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
253c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
253d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
253e0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
253f0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
25400 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
25410 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
25420 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
25430 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25440 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
25450 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
25460 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
25470 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25480 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
25490 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
254a0 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
254b0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
254c0 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
254d0 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
254e0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
254f0 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
25500 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
25510 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
25520 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
25530 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
25540 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
25550 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
25560 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
25570 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
25580 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
25590 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
255a0 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
255b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
255c0 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
255d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
255e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
255f0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
25600 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
25610 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
25620 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
25630 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
25640 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
25650 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
25660 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
25670 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
25680 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
25690 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
256a0 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
256b0 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
256c0 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
256d0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
256e0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
256f0 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
25700 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
25710 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
25720 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
25730 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
25740 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
25750 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
25760 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
25770 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
25780 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
25790 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
257a0 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
257b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
257c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
257d0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
257e0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
257f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25800 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
25810 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
25820 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
25830 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
25840 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
25850 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
25860 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
25870 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
25880 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
25890 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
258a0 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
258b0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
258c0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
258d0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
258e0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
258f0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
25900 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
25910 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
25920 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
25930 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
25940 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
25950 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
25960 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
25970 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
25980 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
25990 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
259a0 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
259b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
259c0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
259d0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
259e0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
259f0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
25a00 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
25a10 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
25a20 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
25a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
25a40 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
25a50 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
25a60 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
25a70 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
25a80 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
25a90 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
25aa0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
25ab0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
25ac0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25ad0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
25ae0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
25af0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
25b00 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25b10 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
25b20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
25b30 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
25b40 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
25b50 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
25b60 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
25b70 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
25b80 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
25b90 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
25ba0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
25bb0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
25bc0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
25bd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
25be0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
25bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
25c00 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
25c10 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
25c20 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
25c30 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
25c40 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25c60 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
25c70 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
25c80 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
25c90 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
25ca0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
25cb0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
25cc0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
25cd0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
25ce0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
25cf0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
25d00 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
25d10 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25d20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25d30 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
25d40 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
25d50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25d60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25d70 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
25d80 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
25d90 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
25da0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
25db0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25dc0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25dd0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
25de0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
25df0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
25e00 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
25e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25e20 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
25e30 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
25e40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25e50 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
25e60 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
25e70 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
25e80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
25e90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
25ea0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
25eb0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25ec0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
25ed0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
25ee0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
25ef0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
25f00 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25f10 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
25f20 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
25f30 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
25f40 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
25f50 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
25f60 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
25f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
25f80 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
25f90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
25fa0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
25fb0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
25fc0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
25fd0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
25fe0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
25ff0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
26000 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
26010 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
26020 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26030 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
26040 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
26050 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26060 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26070 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
26080 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
26090 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
260a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
260b0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
260c0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
260d0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
260e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
260f0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
26100 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
26110 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
26120 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
26130 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
26140 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
26150 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
26160 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
26170 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
26180 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
26190 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
261a0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
261b0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
261c0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
261d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
261e0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
261f0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
26200 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
26210 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
26220 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
26230 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
26240 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
26250 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
26260 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
26270 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
26280 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
26290 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
262a0 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
262b0 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
262c0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
262d0 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
262e0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
262f0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
26300 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
26310 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
26320 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
26330 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
26340 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
26350 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
26360 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
26370 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
26380 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
26390 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
263a0 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
263b0 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
263c0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
263d0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
263e0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
263f0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
26400 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
26410 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
26420 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
26430 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
26440 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26450 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
26460 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
26470 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
26480 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
26490 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
264a0 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
264b0 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
264c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
264d0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
264e0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
264f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26500 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
26510 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
26520 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
26530 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
26540 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
26550 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
26560 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
26570 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
26580 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
26590 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
265a0 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
265b0 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
265c0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
265d0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
265e0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
265f0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
26600 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
26610 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
26620 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
26630 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
26640 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
26650 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
26660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26670 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26680 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
26690 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
266a0 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
266b0 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
266c0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
266d0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
266e0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
266f0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
26700 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
26710 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
26720 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
26730 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
26740 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
26750 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
26760 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
26770 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
26780 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
26790 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
267a0 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
267b0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
267c0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
267d0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
267e0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
267f0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
26800 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
26810 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
26820 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
26830 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
26840 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
26850 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
26860 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
26870 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26880 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26890 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
268a0 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
268b0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
268c0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
268d0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
268e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
268f0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
26900 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
26910 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
26920 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
26930 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
26940 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
26950 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
26960 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26970 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
26980 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
26990 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
269a0 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
269b0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
269c0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
269d0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
269e0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
269f0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
26a00 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
26a10 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
26a20 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
26a30 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
26a40 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
26a50 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
26a60 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
26a70 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
26a80 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
26a90 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
26aa0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
26ab0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
26ac0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
26ad0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
26ae0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
26af0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
26b00 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
26b10 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
26b20 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
26b30 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
26b40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26b50 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
26b60 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
26b70 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
26b80 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
26b90 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
26ba0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
26bb0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
26bc0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
26bd0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
26be0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
26bf0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
26c00 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
26c10 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
26c20 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
26c30 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
26c40 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
26c50 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
26c60 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
26c70 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
26c80 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
26c90 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26ca0 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
26cb0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
26cc0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
26cd0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
26ce0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
26cf0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
26d00 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
26d10 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
26d20 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
26d30 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
26d40 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
26d50 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
26d60 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26d70 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
26d80 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
26d90 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
26da0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
26db0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
26dc0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
26dd0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
26de0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26df0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
26e00 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
26e10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
26e20 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
26e30 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
26e40 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
26e50 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
26e60 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
26e70 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
26e80 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
26e90 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
26ea0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
26eb0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
26ec0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
26ed0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
26ee0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
26ef0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
26f00 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
26f10 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
26f20 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
26f30 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
26f40 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
26f50 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
26f60 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
26f70 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
26f80 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
26f90 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
26fa0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
26fb0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
26fc0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
26fd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26fe0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26ff0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
27000 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
27010 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27020 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
27030 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
27040 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
27050 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27060 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
27070 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
27080 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
27090 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
270a0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
270b0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
270c0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
270d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
270e0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
270f0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
27100 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
27110 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
27120 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
27130 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
27140 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
27150 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
27160 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
27170 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
27180 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
27190 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
271a0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
271b0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
271c0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
271d0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
271e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
271f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
27200 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
27210 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
27220 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
27230 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
27240 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
27250 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
27260 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
27270 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
27280 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
27290 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
272a0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
272b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
272c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
272d0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
272e0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
272f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
27300 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
27310 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27320 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
27330 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27340 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
27350 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
27360 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
27370 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
27380 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
27390 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
273a0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
273b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
273c0 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
273d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
273e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
273f0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
27400 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
27410 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
27420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
27430 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
27440 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
27450 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
27460 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27470 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
27480 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
27490 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
274a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
274b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
274c0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
274d0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
274e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
274f0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
27500 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
27510 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
27520 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
27530 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
27540 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
27550 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
27560 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
27570 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
27580 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
27590 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
275a0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
275b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
275c0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
275d0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
275e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
275f0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
27600 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
27610 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
27620 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
27630 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
27640 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
27650 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
27660 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
27670 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27680 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
27690 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
276a0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
276b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
276c0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
276d0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
276e0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
276f0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
27700 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
27710 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
27720 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
27730 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
27740 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
27750 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
27760 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
27770 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
27780 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
27790 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
277a0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
277b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
277c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
277d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
277e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
277f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
27800 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
27810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27820 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
27830 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27840 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
27850 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27860 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27870 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
27880 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
27890 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
278a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
278b0 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
278c0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
278d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
278e0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
278f0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
27900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27910 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
27920 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
27930 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
27940 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
27950 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
27960 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
27970 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
27980 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
27990 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
279a0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
279b0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
279c0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
279d0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
279e0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
279f0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
27a00 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
27a10 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
27a20 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
27a30 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
27a40 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
27a50 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
27a60 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
27a70 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
27a80 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
27a90 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
27aa0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
27ab0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
27ac0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
27ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27ae0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
27af0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
27b00 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
27b10 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
27b20 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
27b30 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
27b40 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27b50 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
27b60 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
27b70 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
27b80 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
27b90 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
27ba0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
27bb0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
27bc0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
27bd0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27be0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
27bf0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
27c00 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
27c10 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
27c20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27c30 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27c40 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27c50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27c60 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
27c70 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27c80 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27c90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27ca0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
27cb0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
27cc0 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
27cd0 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
27ce0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
27cf0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
27d00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
27d10 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
27d20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
27d30 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
27d40 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
27d50 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
27d60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
27d70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27d80 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27d90 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
27da0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27db0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27dc0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
27dd0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27de0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
27df0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
27e00 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
27e10 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
27e20 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
27e30 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
27e40 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27e50 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27e60 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27e70 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27e80 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27e90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27ea0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27eb0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27ec0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27ed0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27ee0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27ef0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27f00 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
27f10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
27f20 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
27f30 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
27f40 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
27f50 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27f60 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
27f70 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
27f80 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
27f90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
27fa0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
27fb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
27fc0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
27fd0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
27fe0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
27ff0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
28000 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
28010 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
28020 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
28030 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
28040 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
28050 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28060 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
28070 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
28080 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
28090 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
280a0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
280b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
280c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
280d0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
280e0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
280f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
28100 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
28110 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
28120 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
28130 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
28140 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
28150 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
28160 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
28170 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
28180 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
28190 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
281a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
281b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
281c0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
281d0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
281e0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
281f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
28200 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
28210 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
28220 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
28230 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
28240 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
28250 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
28260 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
28270 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28280 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28290 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
282a0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
282b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
282c0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
282d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
282e0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
282f0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
28300 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
28310 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28320 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
28330 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
28340 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
28350 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
28360 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
28370 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28380 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
28390 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
283a0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
283b0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
283c0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
283d0 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
283e0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
283f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28400 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
28410 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
28420 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
28430 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
28440 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
28450 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
28460 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
28470 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28480 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
28490 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
284a0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
284b0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
284c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
284d0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
284e0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
284f0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
28500 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
28510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
28520 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
28530 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
28540 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
28550 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
28560 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
28570 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
28580 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
28590 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
285a0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
285b0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
285c0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
285d0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
285e0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
285f0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
28600 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
28610 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
28620 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
28630 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
28640 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
28650 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
28660 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
28670 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
28680 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
28690 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
286a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
286b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
286c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
286d0 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
286e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
286f0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
28700 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
28710 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
28720 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
28730 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
28740 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
28750 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
28760 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
28770 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
28780 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
28790 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
287a0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
287b0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
287c0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
287d0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
287e0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
287f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
28800 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
28810 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
28820 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
28830 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
28840 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
28850 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
28860 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
28870 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
28880 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
28890 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
288a0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
288b0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
288c0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
288d0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
288e0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
288f0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28900 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
28910 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28920 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
28930 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
28940 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28950 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
28960 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
28970 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
28980 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
28990 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
289a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
289b0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
289c0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
289d0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
289e0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
289f0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
28a00 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
28a10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
28a20 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
28a30 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
28a40 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
28a50 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
28a60 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
28a70 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
28a80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28a90 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28aa0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
28ab0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
28ac0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
28ad0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
28ae0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
28af0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
28b00 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
28b10 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
28b20 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
28b30 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
28b40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
28b50 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
28b60 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
28b70 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
28b80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
28b90 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
28ba0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
28bb0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
28bc0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
28bd0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
28be0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
28bf0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
28c00 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
28c10 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
28c20 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
28c30 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
28c40 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
28c50 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
28c60 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
28c70 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
28c80 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
28c90 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
28ca0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
28cb0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
28cc0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
28cd0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
28ce0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
28cf0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
28d00 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
28d10 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
28d20 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
28d30 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
28d40 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
28d50 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
28d60 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
28d70 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
28d80 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
28d90 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
28da0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
28db0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
28dc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
28dd0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
28de0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
28df0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
28e00 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
28e10 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
28e20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
28e30 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
28e40 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
28e50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28e60 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
28e70 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28e80 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28e90 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
28ea0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
28eb0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
28ec0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
28ed0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28ee0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
28ef0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
28f00 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
28f10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
28f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28f30 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
28f40 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
28f50 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28f60 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28f70 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
28f80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28f90 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28fa0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28fb0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
28fc0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28fd0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
28fe0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28ff0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
29000 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29010 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
29020 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
29030 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29040 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
29050 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
29060 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
29070 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29080 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
29090 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
290a0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
290b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
290c0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
290d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
290e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
290f0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
29100 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
29110 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
29120 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
29130 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
29140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29150 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
29160 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
29170 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
29180 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
29190 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
291a0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
291b0 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
291c0 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
291d0 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
291e0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
291f0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
29200 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
29210 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
29220 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
29230 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
29240 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
29250 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
29260 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
29270 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
29280 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
29290 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
292a0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
292b0 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
292c0 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
292d0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
292e0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
292f0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
29300 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
29310 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
29320 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
29330 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
29340 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
29350 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
29360 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
29370 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
29380 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
29390 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
293a0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
293b0 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
293c0 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
293d0 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
293e0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
293f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
29400 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
29410 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
29420 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
29430 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
29440 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
29450 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
29460 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
29470 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
29480 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
29490 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
294a0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
294b0 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
294c0 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
294d0 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
294e0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
294f0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
29500 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
29510 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
29520 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
29530 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
29540 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
29550 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
29560 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
29570 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29580 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29590 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
295a0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
295b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
295c0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
295d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
295e0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
295f0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
29600 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
29610 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
29620 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29630 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
29640 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
29650 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
29660 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29670 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29680 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
29690 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
296a0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
296b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
296c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
296d0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
296e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
296f0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
29700 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
29710 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
29720 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
29730 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
29740 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
29750 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29760 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
29770 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
29780 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
29790 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
297a0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
297b0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
297c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
297d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
297e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
297f0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
29800 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
29810 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29820 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
29830 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
29840 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
29850 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
29860 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29870 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
29880 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
29890 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
298a0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
298b0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
298c0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
298d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
298e0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
298f0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
29900 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
29910 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
29920 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
29930 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
29940 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
29950 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
29960 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29970 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
29980 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
29990 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
299a0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
299b0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
299c0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
299d0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
299e0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
299f0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
29a00 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
29a10 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
29a20 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
29a30 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
29a40 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
29a50 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
29a60 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
29a70 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
29a80 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
29a90 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
29aa0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
29ab0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
29ac0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29ad0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
29ae0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
29af0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
29b00 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
29b10 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
29b20 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
29b30 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
29b40 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
29b50 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
29b60 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29b70 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
29b80 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
29b90 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
29ba0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
29bb0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
29bc0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
29bd0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
29be0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
29bf0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
29c00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29c10 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
29c20 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
29c30 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
29c40 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
29c50 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
29c60 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
29c70 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
29c80 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29c90 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
29ca0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
29cb0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
29cc0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
29cd0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
29ce0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
29cf0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
29d00 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29d10 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29d20 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
29d30 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29d40 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
29d50 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
29d60 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
29d70 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
29d80 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
29d90 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
29da0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
29db0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
29dc0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
29dd0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
29de0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
29df0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
29e00 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
29e10 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
29e20 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
29e30 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29e40 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
29e50 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
29e60 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
29e70 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29e80 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
29e90 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
29ea0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
29eb0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
29ec0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
29ed0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
29ee0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
29ef0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
29f00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
29f10 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
29f20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
29f30 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29f40 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
29f50 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
29f60 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
29f70 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
29f80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
29f90 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
29fa0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
29fb0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
29fc0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
29fd0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
29fe0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
29ff0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2a000 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a010 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2a020 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2a030 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2a040 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2a050 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2a060 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2a070 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2a080 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a090 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2a0a0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2a0b0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2a0c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a0d0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2a0e0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2a0f0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2a100 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2a110 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2a120 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2a130 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2a140 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2a150 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2a160 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a170 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2a180 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2a190 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2a1a0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2a1b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2a1c0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2a1d0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2a1e0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2a1f0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2a200 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2a210 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a220 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2a230 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2a240 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2a250 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2a260 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2a270 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2a280 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2a290 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2a2a0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2a2b0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2a2c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2a2d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2a2e0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2a2f0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2a300 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a310 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2a320 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2a330 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2a340 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2a350 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2a360 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2a370 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2a380 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2a390 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2a3a0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2a3b0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2a3c0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2a3d0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2a3e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2a3f0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2a400 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2a410 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2a420 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2a430 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2a440 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2a450 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2a460 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2a470 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2a480 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2a490 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2a4a0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2a4b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2a4c0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2a4d0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2a4e0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2a4f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a500 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a510 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2a520 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2a530 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2a540 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2a550 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2a560 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2a570 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2a580 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2a590 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2a5a0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2a5b0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2a5c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2a5d0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2a5e0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2a5f0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2a600 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2a610 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a620 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a630 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2a640 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2a650 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2a660 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2a670 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a680 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2a690 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2a6a0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2a6b0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2a6c0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2a6d0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2a6e0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2a6f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a700 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2a710 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2a720 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2a730 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a740 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2a750 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2a760 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2a770 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2a780 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2a790 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2a7a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2a7b0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2a7c0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2a7d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2a7e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a7f0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2a800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a810 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2a820 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2a830 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2a840 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2a850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2a860 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2a870 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2a880 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2a890 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a8a0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2a8b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a8c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2a8d0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2a8e0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2a8f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2a900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2a910 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2a920 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2a930 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2a940 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a950 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2a960 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2a970 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2a980 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2a990 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2a9a0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2a9b0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2a9c0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2a9d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2a9e0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2a9f0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2aa00 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2aa10 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2aa20 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2aa30 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2aa40 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2aa50 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2aa60 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2aa70 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2aa80 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2aa90 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2aaa0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2aab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2aac0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2aad0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2aae0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2aaf0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2ab00 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2ab10 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2ab20 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2ab30 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2ab40 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2ab50 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2ab60 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2ab70 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2ab80 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2ab90 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2aba0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2abb0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2abc0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2abd0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2abe0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2abf0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2ac00 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2ac10 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2ac20 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2ac30 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2ac40 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2ac50 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2ac60 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2ac70 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2ac80 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2ac90 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2aca0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2acb0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2acc0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2acd0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2ace0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2acf0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2ad00 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2ad10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2ad20 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2ad30 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2ad40 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2ad50 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2ad60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2ad70 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2ad80 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2ad90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2ada0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2adb0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2adc0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2add0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2ade0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2adf0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2ae00 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2ae10 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2ae20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2ae30 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2ae40 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2ae50 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2ae60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2ae70 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2ae80 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2ae90 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2aea0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2aeb0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2aec0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2aed0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2aee0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2aef0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2af00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2af10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2af20 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2af30 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2af40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2af50 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2af60 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2af70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2af80 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2af90 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2afa0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2afb0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2afc0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2afd0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2afe0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2aff0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2b000 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2b010 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2b020 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2b030 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2b040 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b050 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2b060 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2b070 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2b080 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2b090 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2b0a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2b0b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2b0c0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2b0d0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2b0e0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2b0f0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2b100 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2b110 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2b120 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2b130 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2b140 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b150 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b160 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2b170 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2b180 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2b190 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2b1a0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2b1b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b1c0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2b1d0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2b1e0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2b1f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2b200 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2b210 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b220 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2b230 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2b240 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2b250 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2b260 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2b270 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2b280 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2b290 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2b2a0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2b2b0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2b2c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2b2d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b2e0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2b2f0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2b300 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2b310 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2b320 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2b330 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2b340 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2b350 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2b360 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b370 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2b380 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2b390 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2b3a0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2b3b0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2b3c0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2b3d0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2b3e0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2b3f0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2b400 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2b410 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2b420 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2b430 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2b440 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2b450 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2b460 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2b470 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b480 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2b490 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2b4a0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2b4b0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2b4c0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2b4d0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2b4e0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2b4f0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2b500 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b510 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2b520 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2b530 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2b540 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2b550 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2b560 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2b570 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2b580 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2b590 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2b5a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b5b0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2b5c0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2b5d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2b5e0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2b5f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2b600 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b610 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2b620 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2b630 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2b640 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2b650 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b660 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2b670 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2b680 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2b690 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2b6a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b6b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2b6c0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2b6d0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2b6e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b6f0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2b700 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b710 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2b720 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2b730 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2b740 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2b750 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2b760 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2b770 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b780 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2b790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b7a0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2b7b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2b7c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2b7d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2b7e0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2b7f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b800 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2b810 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2b820 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2b830 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2b840 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2b850 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2b860 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2b870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b880 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2b890 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2b8a0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2b8b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b8c0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2b8d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b8e0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2b8f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b900 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2b910 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2b920 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2b930 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2b940 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2b950 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2b960 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2b970 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2b980 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2b990 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2b9a0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2b9b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b9c0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2b9d0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2b9e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b9f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ba00 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2ba10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ba20 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2ba30 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2ba40 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2ba50 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2ba60 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2ba70 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2ba80 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2ba90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2baa0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2bab0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2bac0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2bad0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2bae0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2baf0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2bb00 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2bb10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2bb20 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2bb30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bb40 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2bb50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2bb60 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2bb70 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2bb80 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2bb90 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2bba0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2bbb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2bbc0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2bbd0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2bbe0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2bbf0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2bc00 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2bc10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2bc20 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2bc30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2bc40 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2bc50 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2bc60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bc70 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2bc80 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2bc90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2bca0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2bcb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2bcc0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2bcd0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2bce0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bcf0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2bd00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2bd10 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2bd20 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2bd30 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2bd40 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2bd50 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2bd60 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2bd70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2bd80 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2bd90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2bda0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2bdb0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2bdc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2bdd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2bde0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2bdf0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2be00 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2be10 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2be20 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2be30 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2be40 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2be50 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2be60 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2be70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2be80 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2be90 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2bea0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2beb0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2bec0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2bed0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2bee0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2bef0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2bf00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2bf10 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2bf20 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2bf30 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2bf40 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2bf50 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2bf60 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2bf70 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2bf80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2bf90 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2bfa0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2bfb0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2bfc0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2bfd0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2bfe0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2bff0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2c000 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2c010 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2c020 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2c030 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2c040 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2c050 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2c060 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2c070 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2c080 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2c090 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2c0a0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2c0b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2c0c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2c0d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2c0e0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2c0f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2c100 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2c110 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2c120 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2c130 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2c140 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2c150 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2c160 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
2c170 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2c180 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2c190 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2c1a0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2c1b0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2c1c0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2c1d0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2c1e0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
2c1f0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2c200 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2c210 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
2c220 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2c230 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2c240 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2c250 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
2c260 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2c270 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2c280 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2c290 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2c2a0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2c2b0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2c2c0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2c2d0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2c2e0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2c2f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2c300 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2c310 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
2c320 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2c330 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2c340 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2c350 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2c360 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2c370 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2c380 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2c390 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2c3a0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2c3b0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2c3c0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2c3d0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2c3e0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2c3f0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2c400 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2c410 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2c420 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2c430 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2c440 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2c450 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2c460 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2c470 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2c480 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2c490 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2c4a0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2c4b0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2c4c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2c4d0 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2c4e0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2c4f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2c500 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2c510 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c520 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2c530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c540 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2c550 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c560 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2c570 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2c580 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2c590 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2c5a0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2c5b0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2c5c0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2c5d0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2c5e0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c5f0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2c600 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c610 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2c620 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2c630 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2c640 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2c650 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2c660 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2c670 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2c680 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2c690 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c6a0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2c6b0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2c6c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c6d0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2c6e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c6f0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2c700 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2c710 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2c720 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2c730 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2c740 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c750 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2c760 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2c770 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2c780 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2c790 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2c7a0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2c7b0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2c7c0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2c7d0 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2c7e0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2c7f0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2c800 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2c810 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2c820 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2c830 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2c840 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2c850 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2c860 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2c870 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c880 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2c890 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2c8a0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2c8b0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2c8c0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2c8d0 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2c8e0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2c8f0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2c900 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2c910 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2c920 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2c930 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2c940 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2c950 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2c960 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2c970 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2c980 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2c990 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2c9a0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2c9b0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2c9c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2c9d0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2c9e0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c9f0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2ca00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ca10 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2ca20 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2ca30 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2ca40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2ca50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ca60 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2ca70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ca80 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2ca90 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2caa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2cab0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2cac0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2cad0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2cae0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2caf0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2cb00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2cb10 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2cb20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2cb30 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2cb40 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2cb50 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2cb60 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2cb70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cb80 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2cb90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2cba0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2cbb0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2cbc0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2cbd0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2cbe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cbf0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2cc00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2cc10 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2cc20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cc30 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2cc40 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2cc50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cc60 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2cc70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2cc80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2cc90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2cca0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2ccb0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2ccc0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2ccd0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2cce0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2ccf0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2cd00 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2cd10 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2cd20 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2cd30 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2cd40 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2cd50 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2cd60 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2cd70 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2cd80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2cd90 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2cda0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2cdb0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2cdc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2cdd0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2cde0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2cdf0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2ce00 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2ce10 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2ce20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2ce30 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2ce40 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2ce50 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2ce60 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2ce70 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2ce80 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2ce90 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2cea0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2ceb0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2cec0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2ced0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2cee0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2cef0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2cf00 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2cf10 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2cf20 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2cf30 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2cf40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cf50 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2cf60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cf70 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2cf80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2cf90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cfa0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2cfb0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cfc0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cfd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2cfe0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2cff0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2d000 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2d010 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2d020 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2d030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d040 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2d050 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2d060 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d070 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d080 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2d090 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d0a0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2d0b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d0c0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2d0d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d0e0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2d0f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d100 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d110 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2d120 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d130 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2d140 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d150 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d160 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d180 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2d190 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2d1a0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2d1b0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d1c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2d1d0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2d1e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d1f0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2d200 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2d210 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2d220 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2d230 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2d240 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2d250 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2d260 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2d270 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2d280 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2d290 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2d2a0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2d2b0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2d2c0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2d2d0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2d2e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2d2f0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2d300 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2d310 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2d320 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2d330 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2d340 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d350 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2d360 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2d370 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2d380 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2d390 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2d3a0 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2d3b0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2d3c0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2d3d0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2d3e0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2d3f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d400 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2d410 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2d420 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2d430 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2d440 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2d450 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2d460 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d470 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2d480 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2d490 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2d4a0 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2d4b0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2d4c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2d4d0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2d4e0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2d4f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2d500 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2d510 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2d520 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2d530 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2d540 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2d550 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2d560 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d570 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2d580 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2d590 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2d5a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d5b0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2d5c0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2d5d0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2d5e0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2d5f0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2d600 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2d610 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2d620 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2d630 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2d640 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2d650 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d660 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d670 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d680 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2d690 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d6a0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d6b0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d6c0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d6d0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d6e0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d6f0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d700 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d710 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2d720 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2d730 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2d740 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2d750 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2d760 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2d770 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2d780 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2d790 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2d7a0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2d7b0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2d7c0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2d7d0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2d7e0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2d7f0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d800 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d810 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d820 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2d830 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d840 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d850 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2d860 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d870 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2d880 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2d890 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d8a0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2d8b0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2d8c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2d8d0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2d8e0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2d8f0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2d900 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2d910 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2d920 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2d930 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2d940 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2d950 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d960 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d970 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2d980 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d990 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2d9a0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2d9b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d9c0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d9d0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d9e0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2d9f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2da00 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2da10 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2da20 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2da30 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2da40 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2da50 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2da60 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2da70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2da80 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2da90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2daa0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2dab0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2dac0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2dad0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2dae0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2daf0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2db00 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2db10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2db20 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2db30 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2db40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2db50 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2db60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2db70 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2db80 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2db90 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2dba0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2dbb0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2dbc0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2dbd0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2dbe0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2dbf0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2dc00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2dc10 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2dc20 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2dc30 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2dc40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2dc50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2dc60 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2dc70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2dc80 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2dc90 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2dca0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2dcb0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2dcc0 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2dcd0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2dce0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2dcf0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2dd00 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2dd10 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2dd20 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2dd30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dd40 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2dd50 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2dd60 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2dd70 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2dd80 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2dd90 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2dda0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2ddb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2ddc0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2ddd0 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2dde0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2ddf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2de00 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2de10 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2de20 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2de30 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2de40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2de50 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2de60 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2de70 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2de80 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2de90 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2dea0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2deb0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2dec0 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2ded0 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2dee0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2def0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2df00 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2df10 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2df20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2df30 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2df40 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2df50 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2df60 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2df70 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2df80 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2df90 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2dfa0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2dfb0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2dfc0 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2dfd0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2dfe0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2dff0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2e000 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2e010 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2e020 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2e030 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e040 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2e050 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2e060 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2e070 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2e080 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2e090 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2e0a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2e0b0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2e0c0 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2e0d0 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2e0e0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2e0f0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2e100 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2e110 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2e120 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2e130 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2e140 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2e150 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2e160 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2e170 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2e180 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2e190 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2e1a0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2e1b0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e1c0 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2e1d0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2e1e0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2e1f0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2e200 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2e210 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2e220 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2e230 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2e240 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2e250 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2e260 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2e270 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2e280 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2e290 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2e2a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2e2b0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2e2c0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2e2d0 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2e2e0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2e2f0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2e300 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2e310 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e320 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2e330 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2e340 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2e350 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2e360 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2e370 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2e380 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2e390 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2e3a0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2e3b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e3c0 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2e3d0 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2e3e0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2e3f0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2e400 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2e410 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2e420 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2e430 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e440 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e450 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e460 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e470 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e480 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e490 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e4a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e4b0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2e4c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2e4d0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2e4e0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2e4f0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2e500 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2e510 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2e520 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2e530 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2e540 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e550 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2e560 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2e570 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2e580 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2e590 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2e5a0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2e5b0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2e5c0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2e5d0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2e5e0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2e5f0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2e600 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2e610 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e620 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e630 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2e640 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2e650 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2e660 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2e670 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2e680 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2e690 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2e6a0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2e6b0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2e6c0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2e6d0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e6e0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2e6f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2e700 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e710 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2e720 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2e730 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2e740 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2e750 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2e760 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2e770 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2e780 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2e790 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2e7a0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2e7b0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2e7c0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2e7d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2e7e0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2e7f0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2e800 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2e810 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2e820 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e830 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2e840 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2e850 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2e860 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2e870 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2e880 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2e890 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2e8a0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2e8b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2e8c0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2e8d0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2e8e0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2e8f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e900 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e910 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2e920 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2e930 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2e940 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2e950 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2e960 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2e970 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2e980 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2e990 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2e9a0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2e9b0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2e9c0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2e9d0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2e9e0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2e9f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2ea00 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2ea10 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2ea20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2ea30 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2ea40 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2ea50 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2ea60 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2ea70 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2ea80 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2ea90 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2eaa0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2eab0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2eac0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2ead0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2eae0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2eaf0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2eb00 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2eb10 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2eb20 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2eb30 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2eb40 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2eb50 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2eb60 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2eb70 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2eb80 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2eb90 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2eba0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2ebb0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2ebc0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2ebd0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2ebe0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2ebf0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2ec00 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2ec10 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2ec20 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2ec30 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2ec40 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2ec50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ec60 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2ec70 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2ec80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ec90 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2eca0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2ecb0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2ecc0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2ecd0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2ece0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2ecf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ed00 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2ed10 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2ed20 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2ed30 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2ed40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2ed50 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
2ed60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ed70 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2ed80 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2ed90 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2eda0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2edb0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2edc0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2edd0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2ede0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2edf0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ee00 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2ee10 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2ee20 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2ee30 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2ee40 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2ee50 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2ee60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2ee70 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2ee80 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2ee90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2eea0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2eeb0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2eec0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2eed0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2eee0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2eef0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2ef00 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2ef10 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2ef20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2ef30 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ef40 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2ef50 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2ef60 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2ef70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef80 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2ef90 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2efa0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2efb0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2efc0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2efd0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2efe0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2eff0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2f000 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2f010 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2f020 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2f030 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f040 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f050 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2f060 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2f070 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2f080 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2f090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2f0a0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2f0b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f0c0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2f0d0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2f0e0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2f0f0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2f100 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2f110 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2f120 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2f130 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2f140 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f150 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2f160 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f170 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2f180 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f190 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2f1a0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2f1b0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2f1c0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2f1d0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2f1e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f1f0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2f200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f210 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2f220 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2f230 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2f240 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2f250 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2f260 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2f270 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2f280 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2f290 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2f2a0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2f2b0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2f2c0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2f2d0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2f2e0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2f2f0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2f300 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2f310 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2f320 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2f330 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2f340 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2f350 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2f360 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2f370 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2f380 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2f390 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2f3a0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2f3b0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2f3c0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2f3d0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2f3e0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2f3f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f400 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2f410 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2f420 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2f430 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f440 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2f450 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2f460 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2f470 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2f480 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2f490 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2f4a0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f4b0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2f4c0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2f4d0 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2f4e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f4f0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2f500 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2f510 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2f520 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2f530 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2f540 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2f550 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2f560 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2f570 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2f580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2f590 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2f5a0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2f5b0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2f5c0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2f5d0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2f5e0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2f5f0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2f600 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2f610 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2f620 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2f630 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2f640 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2f650 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2f660 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2f670 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2f680 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2f690 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2f6a0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2f6b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2f6c0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2f6d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f6e0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f6f0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2f700 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2f710 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2f720 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2f730 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2f740 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f750 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2f760 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2f770 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2f780 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f790 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2f7a0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2f7b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f7c0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2f7d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2f7e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2f7f0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2f800 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2f810 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2f820 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2f830 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f840 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f850 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2f860 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2f870 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f880 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2f890 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2f8a0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2f8b0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f8c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2f8d0 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2f8e0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2f8f0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2f900 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2f910 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2f920 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2f930 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2f940 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2f950 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2f960 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2f970 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2f980 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f990 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2f9a0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2f9b0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2f9c0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2f9d0 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2f9e0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2f9f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2fa00 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2fa10 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2fa20 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2fa30 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2fa40 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2fa50 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2fa60 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2fa70 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2fa80 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fa90 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2faa0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2fab0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2fac0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2fad0 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2fae0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2faf0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2fb00 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2fb10 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2fb20 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2fb30 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2fb40 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2fb50 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2fb60 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2fb70 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2fb80 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2fb90 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2fba0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2fbb0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2fbc0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2fbd0 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2fbe0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2fbf0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2fc00 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2fc10 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2fc20 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2fc30 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2fc40 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2fc50 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2fc60 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2fc70 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2fc80 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2fc90 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2fca0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2fcb0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2fcc0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2fcd0 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2fce0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2fcf0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2fd00 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2fd10 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2fd20 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2fd30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2fd40 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2fd50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2fd60 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2fd70 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2fd80 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2fd90 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fda0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2fdb0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2fdc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2fdd0 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2fde0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2fdf0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2fe00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2fe10 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2fe20 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2fe30 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2fe40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2fe50 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2fe60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2fe70 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
2fe80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2fe90 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2fea0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2feb0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2fec0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2fed0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2fee0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2fef0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2ff00 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2ff10 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2ff20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2ff30 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2ff40 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2ff50 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2ff60 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2ff70 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2ff80 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ff90 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2ffa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ffb0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2ffc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ffd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ffe0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2fff0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
30000 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
30010 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
30020 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
30030 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30040 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
30050 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
30060 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30070 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30080 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30090 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
300a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
300b0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
300c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
300d0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
300e0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
300f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
30100 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
30110 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
30120 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
30130 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
30140 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
30150 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
30160 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
30170 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30180 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
30190 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
301a0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
301b0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
301c0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
301d0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
301e0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
301f0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
30200 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
30210 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
30220 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
30230 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
30240 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30250 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
30260 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30270 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
30280 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
30290 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
302a0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
302b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
302c0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
302d0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
302e0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
302f0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
30300 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
30310 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
30320 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
30330 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
30340 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
30350 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
30360 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
30370 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
30380 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
30390 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
303a0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
303b0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
303c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
303d0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
303e0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
303f0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
30400 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
30410 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
30420 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
30430 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
30440 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
30450 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
30460 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
30470 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30480 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30490 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
304a0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
304b0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
304c0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
304d0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
304e0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
304f0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
30500 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
30510 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
30520 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
30530 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30540 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
30550 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
30560 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
30570 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
30580 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
30590 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
305a0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
305b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
305c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
305d0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
305e0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
305f0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
30600 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
30610 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
30620 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
30630 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
30640 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
30650 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
30660 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
30670 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30680 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
30690 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
306a0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
306b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
306c0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
306d0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
306e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
306f0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
30700 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
30710 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
30720 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
30730 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
30740 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
30750 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
30760 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
30770 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
30780 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30790 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
307a0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
307b0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
307c0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
307d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
307e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
307f0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
30800 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
30810 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
30820 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
30830 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
30840 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
30850 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
30860 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
30870 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
30880 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
30890 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
308a0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
308b0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
308c0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
308d0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
308e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
308f0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
30900 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
30910 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
30920 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
30930 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
30940 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
30950 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
30960 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
30970 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
30980 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30990 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
309a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
309b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
309c0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
309d0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
309e0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
309f0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
30a00 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30a10 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
30a20 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
30a30 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
30a40 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
30a50 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
30a60 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30a70 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
30a80 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
30a90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30aa0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
30ab0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
30ac0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
30ad0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
30ae0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
30af0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30b00 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
30b10 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
30b20 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
30b30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
30b40 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
30b50 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
30b60 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30b70 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
30b80 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
30b90 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
30ba0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
30bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
30bc0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
30bd0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
30be0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
30bf0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
30c00 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
30c10 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
30c20 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
30c30 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
30c40 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
30c50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
30c60 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
30c70 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
30c80 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
30c90 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
30ca0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
30cb0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
30cc0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
30cd0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
30ce0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
30cf0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
30d00 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
30d10 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
30d20 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
30d30 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
30d40 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
30d50 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
30d60 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
30d70 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30d80 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
30d90 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
30da0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
30db0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
30dc0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
30dd0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30de0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
30df0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
30e00 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
30e10 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
30e20 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
30e30 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
30e40 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
30e50 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
30e60 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
30e70 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
30e80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
30e90 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
30ea0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30eb0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
30ec0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
30ed0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
30ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30ef0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
30f00 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30f10 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
30f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30f30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
30f40 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
30f50 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
30f60 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
30f70 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
30f80 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
30f90 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
30fa0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
30fb0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
30fc0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
30fd0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
30fe0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
30ff0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
31000 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
31010 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
31020 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31030 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
31040 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
31050 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
31060 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
31070 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
31080 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
31090 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
310a0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
310b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
310c0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
310d0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
310e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
310f0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
31100 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
31110 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
31120 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
31130 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
31140 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
31150 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
31160 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
31170 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
31180 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31190 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
311a0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
311b0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
311c0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
311d0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
311e0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
311f0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
31200 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
31210 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
31220 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
31230 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
31240 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
31250 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
31260 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
31270 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
31280 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
31290 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
312a0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
312b0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
312c0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
312d0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
312e0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
312f0 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
31300 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
31310 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
31320 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
31330 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
31340 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
31350 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
31360 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
31370 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
31380 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
31390 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
313a0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
313b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
313c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
313d0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
313e0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
313f0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
31400 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
31410 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
31420 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
31430 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
31440 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
31450 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
31460 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31470 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
31480 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
31490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
314a0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
314b0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
314c0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
314d0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
314e0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
314f0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
31500 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
31510 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
31520 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
31530 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
31540 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31550 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
31560 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
31570 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
31580 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
31590 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
315a0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
315b0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
315c0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
315d0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
315e0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
315f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
31600 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
31610 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
31620 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
31630 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
31640 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
31650 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
31660 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
31670 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
31680 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
31690 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
316a0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
316b0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
316c0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
316d0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
316e0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
316f0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
31700 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
31710 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
31720 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
31730 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
31740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31750 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
31760 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
31770 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
31780 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
31790 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
317a0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
317b0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
317c0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
317d0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
317e0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
317f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
31800 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
31810 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
31820 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
31830 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
31840 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31850 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
31860 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31870 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
31880 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31890 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
318a0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
318b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
318c0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
318d0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
318e0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
318f0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
31900 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
31910 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
31920 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
31930 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
31940 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31950 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
31960 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
31970 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
31980 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
31990 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
319a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
319b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
319c0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
319d0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
319e0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
319f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31a00 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
31a10 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
31a20 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
31a30 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
31a40 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
31a50 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
31a60 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
31a70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
31a80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31aa0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
31ab0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
31ac0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
31ad0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31ae0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31af0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
31b00 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
31b10 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
31b20 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
31b30 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
31b40 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
31b50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31b60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31b70 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
31b80 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
31b90 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
31ba0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31bb0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31bc0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
31bd0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
31be0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
31bf0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
31c00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31c10 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31c30 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
31c40 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
31c50 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
31c60 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
31c70 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
31c80 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
31c90 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
31ca0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
31cb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31cc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31cd0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
31ce0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31cf0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
31d00 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
31d10 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
31d20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
31d30 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31d40 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
31d50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31d60 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
31d70 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
31d80 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
31d90 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
31da0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
31db0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
31dc0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
31dd0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
31de0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31df0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31e00 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31e10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31e20 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
31e30 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
31e40 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
31e50 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
31e60 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
31e70 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
31e80 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
31e90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
31ea0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31eb0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
31ec0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31ed0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
31ee0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31ef0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
31f00 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
31f10 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
31f20 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31f30 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
31f40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
31f50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31f60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31f80 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
31f90 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
31fa0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
31fb0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
31fc0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
31fd0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
31fe0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
31ff0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
32000 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
32010 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
32020 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
32030 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
32040 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32050 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
32060 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
32070 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
32080 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
32090 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
320a0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
320b0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
320c0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
320d0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
320e0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
320f0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
32100 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32110 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
32120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32130 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
32140 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
32150 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
32160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32170 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32180 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
32190 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
321a0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
321b0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
321c0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
321d0 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
321e0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
321f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32200 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32210 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
32220 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
32230 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
32240 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
32250 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
32260 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
32270 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32290 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
322a0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
322b0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
322c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
322d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
322e0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
322f0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
32300 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
32310 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
32320 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32330 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
32340 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32350 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32360 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32370 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32380 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
32390 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
323a0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
323b0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
323c0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
323d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
323e0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
323f0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
32400 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
32410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32420 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32430 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32450 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
32460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32470 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
32480 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
32490 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
324a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
324b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
324c0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
324d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
324e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
324f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
32500 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
32510 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
32520 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
32530 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
32540 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
32550 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
32560 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
32570 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
32580 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
32590 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
325a0 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
325b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
325c0 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
325d0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
325e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
325f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
32600 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
32610 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32620 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32630 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32640 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
32650 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
32660 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
32670 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
32680 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
32690 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
326a0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
326b0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
326c0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
326d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
326e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
326f0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
32700 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
32710 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
32720 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
32730 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32740 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32750 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
32760 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32770 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
32780 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
32790 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
327a0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
327b0 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
327c0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
327d0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
327e0 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
327f0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
32800 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
32810 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
32820 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
32830 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
32840 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
32850 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
32860 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
32870 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
32880 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
32890 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
328a0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
328b0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
328c0 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
328d0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
328e0 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
328f0 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
32900 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
32910 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
32920 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
32930 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
32940 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32960 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32970 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32980 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
32990 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
329a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
329b0 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
329c0 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
329d0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
329e0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
329f0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
32a00 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
32a10 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
32a20 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
32a30 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32a40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
32a50 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
32a60 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
32a70 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
32a80 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
32a90 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
32aa0 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
32ab0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
32ac0 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
32ad0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
32ae0 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
32af0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
32b00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
32b10 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
32b20 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
32b30 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
32b40 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
32b50 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
32b60 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32b70 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32b80 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32b90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32ba0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
32bb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32bc0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
32bd0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
32be0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
32bf0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
32c00 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
32c10 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
32c20 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
32c30 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
32c40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
32c50 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
32c60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32c70 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32c80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32c90 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
32ca0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32cb0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32cc0 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
32cd0 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
32ce0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32cf0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
32d00 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
32d10 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
32d20 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32d30 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
32d40 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
32d50 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
32d60 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
32d70 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
32d80 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
32d90 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
32da0 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
32db0 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
32dc0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
32dd0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
32de0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
32df0 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
32e00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32e10 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
32e20 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
32e30 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
32e40 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32e50 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
32e60 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
32e70 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
32e80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32e90 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
32ea0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
32eb0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
32ec0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32ed0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
32ee0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
32ef0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
32f00 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
32f10 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
32f20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32f30 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
32f40 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
32f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
32f60 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
32f70 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32f80 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32f90 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
32fa0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32fb0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32fc0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32fd0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32fe0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
32ff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33000 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
33010 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33020 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
33030 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
33040 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33060 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
33070 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
33080 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
33090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
330a0 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
330b0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
330c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
330d0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
330e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
330f0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33100 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
33110 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33120 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33130 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
33140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33150 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33160 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
33170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33180 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
33190 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
331a0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
331b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
331c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
331d0 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
331e0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
331f0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
33200 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33210 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33220 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
33230 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33240 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
33250 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33260 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33270 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33280 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33290 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
332a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
332b0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
332c0 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
332d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
332e0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
332f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
33300 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33310 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
33320 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
33330 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
33340 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33350 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33360 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33380 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33390 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
333a0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
333b0 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
333c0 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
333d0 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
333e0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
333f0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
33400 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
33410 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
33420 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
33430 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33440 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
33450 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
33460 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
33470 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33480 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
33490 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
334a0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
334b0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
334c0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
334d0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
334e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
334f0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
33500 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
33510 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
33520 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
33530 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
33540 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
33550 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
33560 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
33570 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
33580 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
33590 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
335a0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
335b0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
335c0 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
335d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
335e0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
335f0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
33600 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
33610 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
33620 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
33630 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
33640 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
33650 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
33660 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
33670 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
33680 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
33690 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
336a0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
336b0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
336c0 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
336d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
336e0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
336f0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
33700 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
33710 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
33720 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
33730 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
33740 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
33750 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
33760 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
33770 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
33780 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
33790 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
337a0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
337b0 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
337c0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
337d0 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
337e0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
337f0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
33800 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
33810 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33820 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33830 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
33840 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
33850 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33860 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33870 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
33880 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
33890 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
338a0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
338b0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
338c0 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
338d0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
338e0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
338f0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
33900 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
33910 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
33920 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
33930 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
33940 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
33950 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
33960 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
33970 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33980 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
33990 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
339a0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
339b0 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
339c0 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
339d0 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
339e0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
339f0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
33a00 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
33a10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
33a20 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
33a30 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
33a40 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
33a50 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33a60 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
33a70 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
33a80 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
33a90 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
33aa0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
33ab0 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
33ac0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
33ad0 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
33ae0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
33af0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
33b00 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
33b10 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
33b20 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
33b30 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
33b40 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
33b50 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
33b60 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
33b70 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
33b80 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
33b90 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
33ba0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
33bb0 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
33bc0 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
33bd0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
33be0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
33bf0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
33c00 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
33c10 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
33c20 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
33c30 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
33c40 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
33c50 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
33c60 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
33c70 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
33c80 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33c90 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
33ca0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
33cb0 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
33cc0 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
33cd0 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
33ce0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
33cf0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
33d00 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
33d10 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
33d20 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
33d30 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
33d40 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
33d50 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
33d60 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
33d70 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
33d80 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33d90 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
33da0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
33db0 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
33dc0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33dd0 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
33de0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
33df0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
33e00 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
33e10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
33e20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
33e30 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33e40 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
33e50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33e60 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
33e70 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
33e80 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
33e90 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33ea0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
33eb0 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
33ec0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
33ed0 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
33ee0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
33ef0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
33f00 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
33f10 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
33f20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
33f30 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
33f40 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
33f50 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
33f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
33f70 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
33f80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
33f90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
33fa0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33fb0 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
33fc0 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
33fd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33fe0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
33ff0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
34000 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
34010 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
34020 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34030 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
34040 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
34050 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
34060 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
34070 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
34080 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
34090 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
340a0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
340b0 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
340c0 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
340d0 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
340e0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
340f0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
34100 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
34110 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
34120 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
34130 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
34140 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
34150 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
34160 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
34170 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
34180 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
34190 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
341a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
341b0 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
341c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
341d0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
341e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
341f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
34200 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
34210 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
34220 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
34230 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
34240 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
34250 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
34260 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
34270 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
34280 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
34290 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
342a0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
342b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
342c0 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
342d0 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
342e0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
342f0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34300 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34310 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
34320 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
34330 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34340 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34350 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
34360 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
34370 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
34380 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34390 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
343a0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
343b0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
343c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
343d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
343e0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
343f0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
34400 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
34410 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
34420 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
34430 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
34440 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
34450 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
34460 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
34470 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34480 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
34490 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
344a0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
344b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
344c0 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
344d0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
344e0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
344f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
34500 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
34510 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
34520 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34530 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
34540 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
34550 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
34560 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
34570 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34580 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
34590 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
345a0 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
345b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
345c0 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
345d0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
345e0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
345f0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
34600 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
34610 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
34620 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
34630 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
34640 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
34650 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
34660 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
34670 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
34680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34690 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
346a0 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
346b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
346c0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
346d0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
346e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
346f0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
34700 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
34710 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
34720 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
34730 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
34740 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
34750 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
34760 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34770 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
34780 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
34790 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
347a0 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
347b0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
347c0 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
347d0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
347e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
347f0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
34800 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
34810 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
34820 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
34830 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
34840 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
34850 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
34860 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
34870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34880 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
34890 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
348a0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
348b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
348c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
348d0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
348e0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
348f0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
34900 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
34910 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
34920 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
34930 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
34940 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34950 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34960 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
34970 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
34980 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34990 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
349a0 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
349b0 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
349c0 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
349d0 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
349e0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
349f0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
34a00 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
34a10 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
34a20 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
34a30 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
34a40 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34a50 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34a60 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34a70 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
34a80 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
34a90 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
34aa0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
34ab0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34ac0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34ad0 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34ae0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34af0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34b00 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
34b10 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
34b20 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
34b30 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
34b40 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
34b50 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
34b60 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
34b70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34b80 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
34b90 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
34ba0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
34bb0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
34bc0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
34bd0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
34be0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
34bf0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
34c00 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
34c10 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
34c20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
34c30 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34c40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34c50 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34c60 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
34c70 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
34c80 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
34c90 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
34ca0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
34cb0 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
34cc0 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
34cd0 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
34ce0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
34cf0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
34d00 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
34d10 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
34d20 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
34d30 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
34d40 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
34d50 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
34d60 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
34d70 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
34d80 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
34d90 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
34da0 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
34db0 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
34dc0 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
34dd0 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
34de0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
34df0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
34e00 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
34e10 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
34e20 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
34e30 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
34e40 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
34e50 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
34e60 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
34e70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34e80 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
34e90 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
34ea0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
34eb0 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
34ec0 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
34ed0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
34ee0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
34ef0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
34f00 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
34f10 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
34f20 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
34f30 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
34f40 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
34f50 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
34f60 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
34f70 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
34f80 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
34f90 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
34fa0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
34fb0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
34fc0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
34fd0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
34fe0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
34ff0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
35000 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
35010 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
35020 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
35030 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
35040 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
35050 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
35060 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
35070 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
35080 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
35090 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
350a0 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
350b0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
350c0 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
350d0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
350e0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
350f0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
35100 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
35110 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
35120 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
35130 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
35140 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
35150 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
35160 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
35170 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
35180 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
35190 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
351a0 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
351b0 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
351c0 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
351d0 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
351e0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
351f0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
35200 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
35210 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
35220 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
35230 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
35240 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
35250 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
35260 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
35270 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
35280 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
35290 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
352a0 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
352b0 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
352c0 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
352d0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
352e0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
352f0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
35300 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
35310 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
35320 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
35330 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
35340 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35350 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35360 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
35370 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
35380 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
35390 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
353a0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
353b0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
353c0 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
353d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
353e0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
353f0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
35400 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
35410 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
35420 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
35430 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35440 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35450 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
35460 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
35470 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
35480 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
35490 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
354a0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
354b0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
354c0 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
354d0 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
354e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
354f0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35500 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
35510 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
35520 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
35530 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
35540 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35550 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35560 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
35570 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
35580 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35590 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
355a0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
355b0 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
355c0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
355d0 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
355e0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
355f0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
35600 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
35610 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
35620 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
35630 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
35640 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
35650 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
35660 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
35670 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
35680 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
35690 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
356a0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
356b0 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
356c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
356d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
356e0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
356f0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
35700 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35710 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
35720 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a  be avoided..**.*
35730 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
35740 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
35750 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
35760 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
35770 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
35780 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
35790 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20   [sqlite3_open] 
357a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
357b0 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65  _v2].  Otherwise
357c0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
357d0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
357e0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
357f0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
35800 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73  y fail.  Here is
35810 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f   an.** example o
35820 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73  f how to do this
35830 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20   using C++ with 
35840 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74  the Windows Runt
35850 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ime:.**.** <bloc
35860 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
35870 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20  LPCWSTR zPath = 
35880 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65  Windows::Storage
35890 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74  ::ApplicationDat
358a0 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20  a::Current->.** 
358b0 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f  &nbsp;     Tempo
358c0 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68  raryFolder->Path
358d0 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61  ->Data();.** cha
358e0 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d  r zPathBuf&#91;M
358f0 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b  AX_PATH + 1&#93;
35900 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74  ;.** memset(zPat
35910 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28  hBuf, 0, sizeof(
35920 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57  zPathBuf));.** W
35930 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79  ideCharToMultiBy
35940 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a  te(CP_UTF8, 0, z
35950 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42  Path, -1, zPathB
35960 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68  uf, sizeof(zPath
35970 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  Buf),.** &nbsp; 
35980 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b      NULL, NULL);
35990 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70  .** sqlite3_temp
359a0 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c  _directory = sql
359b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73  ite3_mprintf("%s
359c0 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a  ", zPathBuf);.**
359d0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
359e0 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ote>.*/.SQLITE_E
359f0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
35a00 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
35a10 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
35a20 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
35a30 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35a40 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
35a50 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
35a60 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35a70 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
35a80 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
35a90 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
35aa0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
35ab0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
35ac0 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
35ad0 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
35ae0 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
35af0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
35b00 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
35b10 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
35b20 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
35b30 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
35b40 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
35b50 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
35b60 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
35b70 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
35b80 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
35b90 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35ba0 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
35bb0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35bc0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
35bd0 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
35be0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
35bf0 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
35c00 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
35c10 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
35c20 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
35c30 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
35c40 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
35c50 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
35c60 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
35c70 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
35c80 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
35c90 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
35ca0 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
35cb0 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
35cc0 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
35cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35ce0 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
35cf0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
35d00 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
35d10 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
35d20 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35d30 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35d40 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35d50 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35d60 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35d70 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35d80 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35d90 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
35da0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35db0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
35dc0 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
35dd0 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
35de0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
35df0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
35e00 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
35e10 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
35e20 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
35e30 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35e40 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35e50 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35e60 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35e70 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35e80 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35e90 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35ea0 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35eb0 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35ec0 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
35ed0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35ee0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
35ef0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
35f00 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
35f10 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
35f20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
35f30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35f40 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35f50 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35f60 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35f70 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35f80 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35f90 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35fa0 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35fb0 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35fc0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35fd0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35fe0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35ff0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
36000 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
36010 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
36020 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
36030 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
36040 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
36050 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
36060 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
36070 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
36080 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
36090 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
360a0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
360b0 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
360c0 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
360d0 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
360e0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
360f0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
36100 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
36110 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
36120 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74  ite3_data_direct
36130 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
36140 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
36150 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
36160 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
36170 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
36180 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36190 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
361a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
361b0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
361c0 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
361d0 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
361e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
361f0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
36200 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
36210 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
36220 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
36230 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
36240 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
36250 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
36260 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
36270 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
36280 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
36290 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
362a0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
362b0 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
362c0 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
362d0 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
362e0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
362f0 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
36300 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
36310 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
36320 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
36330 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
36340 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
36350 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
36360 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
36370 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
36380 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
36390 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
363a0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
363b0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
363c0 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
363d0 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
363e0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
363f0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
36400 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
36410 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
36420 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
36430 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
36440 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
36450 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
36460 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
36470 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
36480 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36490 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
364a0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
364b0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
364c0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
364d0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
364e0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
364f0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
36500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36510 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
36520 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
36530 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36540 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
36550 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
36560 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36570 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36580 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
36590 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
365a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
365b0 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
365c0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
365d0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
365e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
365f0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
36600 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
36610 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
36620 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
36630 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
36640 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
36650 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
36660 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
36670 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
36680 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
36690 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
366a0 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
366b0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
366c0 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
366d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
366e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
366f0 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e  Return The Filen
36700 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61  ame For A Databa
36710 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
36720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36730 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e  _db_filename(D,N
36740 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36750 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36760 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61   a filename.** a
36770 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64  ssociated with d
36780 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e  atabase N of con
36790 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65  nection D.  ^The
367a0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
367b0 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e  ile.** has the n
367c0 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20  ame "main".  If 
367d0 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61  there is no atta
367e0 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20  ched database N 
367f0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  on the database.
36800 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  ** connection D,
36810 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20   or if database 
36820 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79  N is a temporary
36830 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   or in-memory da
36840 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20  tabase, then.** 
36850 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36860 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36870 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  * ^The filename 
36880 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
36890 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
368a0 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a   output of the.*
368b0 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20  * xFullPathname 
368c0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56  method of the [V
368d0 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20  FS].  ^In other 
368e0 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e  words, the filen
368f0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61  ame.** will be a
36900 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e  n absolute pathn
36910 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65  ame, even if the
36920 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a   filename used.*
36930 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  * to open the da
36940 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c  tabase originall
36950 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72  y was a URI or r
36960 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36970 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
36980 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65  *sqlite3_db_file
36990 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62  name(sqlite3 *db
369a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
369b0 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  bName);../*.** C
369c0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
369d0 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ne if a database
369e0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a   is read-only.**
369f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36a00 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e  _db_readonly(D,N
36a10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36a20 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74  rns 1 if the dat
36a30 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f  abase N.** of co
36a40 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65  nnection D is re
36a50 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74  ad-only, 0 if it
36a60 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20   is read/write, 
36a70 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f  or -1 if N is no
36a80 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  t.** the name of
36a90 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63   a database on c
36aa0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a  onnection D..*/.
36ab0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
36ac0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20  eadonly(sqlite3 
36ad0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
36ae0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
36af0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
36b00 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
36b10 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
36b20 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
36b30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
36b40 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
36b50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36b60 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
36b70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
36b80 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36b90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36ba0 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
36bb0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
36bc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
36bd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36be0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
36bf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
36c00 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
36c10 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
36c20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
36c30 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
36c40 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
36c50 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
36c60 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
36c70 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
36c80 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
36c90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36ca0 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
36cb0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
36cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
36cd0 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
36ce0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
36cf0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
36d00 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
36d10 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
36d20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
36d30 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
36d40 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
36d50 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
36d60 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
36d70 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
36d90 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
36da0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
36db0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
36dc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
36dd0 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
36de0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
36df0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
36e00 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
36e10 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
36e20 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
36e30 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
36e40 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
36e50 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
36e60 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
36e70 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36e80 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
36e90 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
36ea0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
36eb0 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
36ec0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36ed0 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
36ee0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
36ef0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
36f00 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
36f10 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
36f20 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
36f30 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
36f40 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
36f50 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
36f60 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
36f70 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36f80 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
36f90 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36fa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36fb0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
36fc0 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
36fd0 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
36fe0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
36ff0 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
37000 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
37010 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
37020 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
37030 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
37040 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
37050 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
37060 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
37070 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37080 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
37090 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
370a0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
370b0 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
370c0 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
370d0 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
370e0 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
370f0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
37100 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
37110 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37120 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
37130 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
37140 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
37150 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
37160 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f  he commit and ro
37170 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
37180 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65  backs are not re
37190 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20  entrant..** The 
371a0 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
371b0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
371c0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
371d0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
371e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
371f0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
37200 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
37210 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
37220 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
37230 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37240 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
37250 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
37260 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
37270 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
37280 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
37290 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
372a0 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
372b0 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
372c0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
372d0 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
372e0 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68   running any oth
372f0 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  er SQL statement
37300 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c  s, including SEL
37310 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  ECT statements,.
37320 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c  ** or merely cal
37330 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
37340 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
37350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37360 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
37370 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37380 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
37390 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
373a0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
373b0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
373c0 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
373d0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
373e0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
373f0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
37400 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
37410 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
37420 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
37430 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
37440 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
37450 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
37460 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
37470 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
37480 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37490 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
374a0 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
374b0 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
374c0 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
374d0 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
374e0 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
374f0 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
37500 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
37510 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
37520 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
37530 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
37540 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
37550 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
37560 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
37570 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
37580 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
37590 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
375a0 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
375b0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
375c0 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
375d0 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
375e0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
375f0 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
37600 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
37610 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
37620 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
37630 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
37640 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
37650 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
37660 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
37670 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
37680 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
37690 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
376a0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
376b0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
376c0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
376d0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
376e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
376f0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
37700 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
37710 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
37720 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
37730 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
37740 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
37750 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
37760 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
37770 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
37780 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
37790 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
377a0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
377b0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
377c0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
377d0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
377e0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
377f0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
37800 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
37810 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
37820 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
37830 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
37840 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
37850 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
37860 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
37870 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
37880 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
37890 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
378a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
378b0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
378c0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
378d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
378e0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
378f0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
37900 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
37910 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
37920 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
37930 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
37940 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
37950 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
37960 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37970 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
37980 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
37990 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
379a0 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
379b0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
379c0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
379d0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
379e0 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
379f0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
37a00 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
37a10 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
37a20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
37a30 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
37a40 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
37a50 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
37a60 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
37a70 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
37a80 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
37a90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
37aa0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
37ab0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
37ac0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
37ad0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
37ae0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37af0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
37b00 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
37b10 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
37b20 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
37b30 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
37b40 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
37b50 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
37b60 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
37b70 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37b80 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
37b90 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
37ba0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
37bb0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
37bc0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
37bd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
37be0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
37bf0 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
37c00 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
37c10 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37c20 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
37c30 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
37c40 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
37c50 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
37c60 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
37c70 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
37c80 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
37c90 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
37ca0 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
37cb0 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
37cc0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
37cd0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
37ce0 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
37cf0 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
37d00 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
37d10 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
37d20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
37d30 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
37d40 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
37d50 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
37d60 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
37d70 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
37d80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37d90 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
37da0 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
37db0 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
37dc0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
37dd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37de0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
37df0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
37e00 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
37e10 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
37e20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37e30 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
37e40 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
37e50 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
37e60 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
37e70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
37e80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
37e90 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
37ea0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
37eb0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
37ec0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
37ed0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
37ee0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
37ef0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
37f00 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
37f10 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
37f20 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
37f30 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
37f40 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
37f50 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37f60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
37f70 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
37f80 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
37f90 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
37fa0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
37fb0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 2c 20 5b  ommit_hook()], [
37fc0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
37fd0 5f 68 6f 6f 6b 28 29 5d 2c 0a 2a 2a 20 61 6e 64  _hook()],.** and
37fe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 75 70 64   [sqlite3_preupd
37ff0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
38000 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f 69 64 20  rfaces..*/.void 
38010 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
38020 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
38030 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
38040 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
38050 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
38060 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
38070 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
38080 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
38090 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
380a0 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
380b0 63 68 65 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  che.**.** ^(This
380c0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
380d0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
380e0 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20   sharing of the 
380f0 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a  database cache.*
38100 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74  * and schema dat
38110 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74  a structures bet
38120 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  ween [database c
38130 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e  onnection | conn
38140 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74  ections].** to t
38150 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
38160 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61  . Sharing is ena
38170 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75  bled if the argu
38180 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20  ment is true.** 
38190 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20  and disabled if 
381a0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  the argument is 
381b0 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  false.)^.**.** ^
381c0 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73  Cache sharing is
381d0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73   enabled and dis
381e0 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74  abled for an ent
381f0 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20  ire process..** 
38200 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65  This is a change
38210 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65   as of SQLite ve
38220 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20  rsion 3.5.0. In 
38230 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f  prior versions o
38240 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61  f SQLite,.** sha
38250 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64  ring was enabled
38260 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72   or disabled for
38270 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70   each thread sep
38280 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
38290 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69  (The cache shari
382a0 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74  ng mode set by t
382b0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66  his interface ef
382c0 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71  fects all subseq
382d0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
382e0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
382f0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
38300 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  _v2()], and [sql
38310 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a  ite3_open16()]..
38320 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61  ** Existing data
38330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
38340 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68   continue use th
38350 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a  e sharing mode.*
38360 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66  * that was in ef
38370 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65  fect at the time
38380 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65   they were opene
38390 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
383a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
383b0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
383c0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
383d0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
383e0 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
383f0 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
38400 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
38410 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e  ned otherwise.)^
38420 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63  .**.** ^Shared c
38430 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64  ache is disabled
38440 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74   by default. But
38450 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e   this might chan
38460 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  ge in.** future 
38470 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
38480 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  te.  Application
38490 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75  s that care abou
384a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
384b0 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64  e setting should
384c0 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74   set it explicit
384d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ly..**.** This i
384e0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
384f0 61 64 73 61 66 65 20 6f 6e 20 70 72 6f 63 65 73  adsafe on proces
38500 73 6f 72 73 20 77 68 65 72 65 20 77 72 69 74 69  sors where writi
38510 6e 67 20 61 0a 2a 2a 20 33 32 2d 62 69 74 20 69  ng a.** 32-bit i
38520 6e 74 65 67 65 72 20 69 73 20 61 74 6f 6d 69 63  nteger is atomic
38530 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f  ..**.** See Also
38540 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65  :  [SQLite Share
38550 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f  d-Cache Mode].*/
38560 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
38570 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
38580 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
38590 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20  PI3REF: Attempt 
385a0 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d  To Free Heap Mem
385b0 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ory.**.** ^The s
385c0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
385d0 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63  emory() interfac
385e0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72  e attempts to fr
385f0 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ee N bytes.** of
38600 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20   heap memory by 
38610 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e  deallocating non
38620 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
38630 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a  y allocations.**
38640 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74   held by the dat
38650 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20  abase library.  
38660 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20   Memory used to 
38670 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a  cache database.*
38680 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f  * pages to impro
38690 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69  ve performance i
386a0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
386b0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
386c0 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  mory..** ^sqlite
386d0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
386e0 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  () returns the n
386f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61  umber of bytes a
38700 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a  ctually freed,.*
38710 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65  * which might be
38720 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68   more or less th
38730 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65  an the amount re
38740 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  quested..** ^The
38750 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
38760 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e  _memory() routin
38770 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74  e is a no-op ret
38780 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69  urning zero.** i
38790 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20  f SQLite is not 
387a0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
387b0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
387c0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
387d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
387e0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c   [sqlite3_db_rel
387f0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a  ease_memory()].*
38800 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
38810 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
38820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38830 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20  EF: Free Memory 
38840 55 73 65 64 20 42 79 20 4