/ Hex Artifact Content
Login

Artifact c7be05ad191d2634292fcc77bdb2bcfa4526eb98:


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 4c 4f 43 4b 45  ine SQLITE_LOCKE
54f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5500: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5510: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5530: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5540: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5550: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5570: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5590: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
55a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
55b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
55c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
55d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
55e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5600: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5610: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5620: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5630: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5640: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5650: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5660: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5670: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5680: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5690: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
56c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
56d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
56e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5700: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5710: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5720: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5730: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5740: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5750: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5760: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5770: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5780: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5790: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
57a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
57b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
57c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
57d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
57e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
57f0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5810: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5820: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5830: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5840: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5860: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5870: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5880: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5890: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
58b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
58c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
58d0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
58e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
58f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5900: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5910: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5920: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
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 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5950: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5960: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* 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 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59a0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* 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 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
59d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59e0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
59f0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a10: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5a20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a30: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5a40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5a70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5a80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
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 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5ab0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
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 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5af0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
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 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5b30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
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 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5b70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
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 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5bb0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
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 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5bf0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
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 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5c30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5c40: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5c50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c70: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5c80: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5c90: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5ca0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5cb0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cc0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5cd0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5ce0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5cf0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d10: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5d20: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5d30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d60: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5d70: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5d80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5d90: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5da0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5db0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5dc0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5dd0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5de0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5df0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5e00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5e10: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5e20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e30: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5e40: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5e50: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5e60: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5e70: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5e80: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5e90: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5ea0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5eb0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5ec0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5ee0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5ef0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5f00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5f10: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
5f20: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
5f30: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
5f40: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
5f50: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5f60: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5f70: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5f80: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5f90: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5fa0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5fb0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
5fc0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
5fd0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
5fe0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5ff0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6000: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6010: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6020: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6030: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6040: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6050: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6060: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6070: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6080: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6090: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
60a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
60b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
60c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
60d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
60e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
60f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6100: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6110: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6120: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6130: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6140: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6150: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6160: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6170: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6180: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6190: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
61a0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
61b0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
61c0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
61d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
61e0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
61f0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6200: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6210: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6220: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6230: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6240: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6250: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
6260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6270: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6280: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6290: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
62a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
62b0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
62c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
62d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
62e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6310: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6320: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6330: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6350: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6360: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6370: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6380: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6390: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
63a0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
63b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
63c0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
63d0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
63e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
63f0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6400: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6410: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6420: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6430: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6440: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6460: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6470: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6480: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6490: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
64a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
64b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
64c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
64d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
64e0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
64f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6500: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6510: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6520: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6530: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6540: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6550: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6560: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6570: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6580: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6590: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
65a0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
65b0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
65c0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
65d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
65e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
65f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6600: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6610: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6620: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6630: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6640: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6650: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6670: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6680: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6690: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
66a0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
66b0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
66c0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
66d0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
66e0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
66f0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6700: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6710: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6720: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6730: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6740: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6750: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6760: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6770: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6780: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6790: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
67a0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
67b0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
67c0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
67d0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
67e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
67f0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6800: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6810: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6820: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6830: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6840: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6850: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6860: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6870: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6880: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6890: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
68a0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
68b0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
68c0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
68d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
68e0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
68f0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6900: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6910: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6920: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6930: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6940: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6950: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6960: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6970: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6980: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6990: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
69a0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
69b0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
69c0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
69d0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
69e0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
69f0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6a00: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6a10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6a20: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6a30: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6a40: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6a50: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6a60: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6a70: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6a80: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6a90: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6aa0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6ab0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6ac0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6ad0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6ae0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6af0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6b00: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6b10: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6b20: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6b30: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6b40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6b50: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6b60: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6b70: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6b80: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6b90: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6ba0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6bb0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6bc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6bd0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6be0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6bf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6c00: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6c10: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6c20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6c30: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6c40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6c50: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6c60: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6c70: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6c80: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6c90: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6ca0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6cb0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6cc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6cd0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6ce0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6cf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6d00: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6d10: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6d20: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6d30: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6d40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6d50: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6d60: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6d70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6d80: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6d90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6da0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6db0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6dc0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6dd0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6de0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6df0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e00: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6e10: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6e20: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6e30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6e40: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6e50: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6e60: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6e70: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6e80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6e90: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6ea0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6eb0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6ec0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6ed0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6ee0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6ef0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
6f00: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6f10: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
6f20: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
6f30: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
6f40: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
6f50: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
6f60: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
6f70: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
6f80: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
6f90: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
6fa0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
6fb0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
6fc0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
6fd0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
6fe0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
6ff0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7000: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7010: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7020: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7030: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7040: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7050: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7060: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7070: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7080: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7090: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
70a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
70b0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
70c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
70d0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
70e0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
70f0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7100: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7110: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7120: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7130: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7140: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7150: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7160: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7170: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7180: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7190: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
71a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
71b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
71c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
71d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
71e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
71f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7200: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7210: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7220: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7230: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7240: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7250: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7260: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7270: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7280: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7290: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
72a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
72b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
72c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
72d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
72e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
72f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7300: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7310: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7320: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7330: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7350: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7360: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7370: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7380: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7390: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
73a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73b0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
73c0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
73d0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
73e0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
73f0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7400: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7410: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7420: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7430: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7440: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7450: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7460: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7470: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7480: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7490: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
74a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
74b0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
74c0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
74d0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
74e0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
74f0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7500: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7510: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7520: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7530: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7540: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7550: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7560: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7570: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7580: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7590: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
75a0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
75b0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
75c0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
75d0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
75e0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
75f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7600: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7610: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7620: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7630: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7640: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7650: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7660: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7670: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7680: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7690: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
76a0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
76b0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
76c0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
76d0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
76e0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
76f0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7700: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7710: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7720: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7730: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7740: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7750: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7760: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7770: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7780: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7790: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
77a0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
77b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
77c0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
77d0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
77e0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
77f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7800: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7810: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7820: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7830: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7840: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7850: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7860: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7870: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7880: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7890: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
78a0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
78b0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
78c0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
78d0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
78e0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
78f0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7900: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7910: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7920: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7930: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7940: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7950: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7960: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7970: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7980: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7990: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
79a0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
79b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
79c0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
79d0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
79e0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
79f0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7a00: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7a10: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7a20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7a40: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7a50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7a60: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7a70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7a80: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7a90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7aa0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7ab0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ac0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7ad0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ae0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7af0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b00: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b20: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7b30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b40: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7b50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7b60: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7b70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7b80: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7b90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7ba0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7bc0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7bd0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7be0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7bf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7c00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7c10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7c20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7c30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7c40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7c50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7c60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7c70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7c80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7c90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7ca0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7cb0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7cc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7cd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7ce0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7cf0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7d00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7d10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7d20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7d30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7d40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7d50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7d60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7d70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7d80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7d90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7da0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7db0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7dc0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7dd0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7de0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7df0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7e00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7e10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7e20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7e30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7e40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7e50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7e60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7e70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7e80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7e90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7ea0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7eb0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7ec0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7ed0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7ee0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7ef0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7f00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
7f10: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7f20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7f30: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
7f40: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
7f50: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
7f60: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7f70: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
7f80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
7f90: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
7fa0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
7fb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
7fc0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
7fd0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
7fe0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
7ff0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8000: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8010: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8020: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8030: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8040: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8050: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8060: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8070: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8080: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8090: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
80a0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
80b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
80c0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
80d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
80e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
80f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8100: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8110: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8120: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8130: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8140: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8150: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8160: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8170: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8180: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8190: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
81a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
81b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
81c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
81d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
81e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
81f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8200: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8210: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8220: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8230: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8240: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8250: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8260: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8270: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8280: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8290: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
82a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
82b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
82c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
82d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
82e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
82f0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8300: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8310: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8320: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8330: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8340: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8350: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
8360: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8370: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8380: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8390: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
83a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
83b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
83c0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
83d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
83e0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
83f0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8400: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8410: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8420: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8430: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8440: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8450: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8460: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8470: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8480: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8490: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
84a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
84b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
84c0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
84d0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
84e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
84f0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8500: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8510: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8520: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8530: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8540: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8550: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8560: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8570: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8580: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8590: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
85a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
85b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
85c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
85d0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
85e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
85f0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8600: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8610: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8620: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8630: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8640: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8650: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8660: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8670: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8680: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8690: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
86a0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
86b0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
86c0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
86d0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
86e0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
86f0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8700: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8710: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8720: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8730: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8740: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8750: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8760: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8770: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8780: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8790: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
87a0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
87b0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
87c0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
87d0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
87e0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
87f0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8800: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8810: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8820: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8830: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8840: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8850: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8870: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8880: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8890: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
88a0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
88b0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
88c0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
88d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
88e0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
88f0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8900: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8910: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8920: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8930: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8940: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8950: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8960: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8970: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8980: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8990: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
89a0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
89b0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
89c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
89d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
89e0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
89f0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8a00: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8a10: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8a20: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8a30: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8a40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8a50: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8a60: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8a70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8a80: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8a90: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8aa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8ab0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8ac0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8ad0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8ae0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8af0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8b00: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8b10: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8b20: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8b30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8b40: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8b50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8b60: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8b70: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8b80: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8b90: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8ba0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8bb0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8bc0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8bd0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8be0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8bf0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8c00: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8c10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8c20: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8c30: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8c40: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8c50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8c60: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8c70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8c80: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8c90: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8ca0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8cb0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8cc0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8cd0: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8ce0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8cf0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8d00: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8d10: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8d20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8d30: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8d40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8d50: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8d60: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8d70: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8d80: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8d90: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8da0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8db0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8dc0: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8dd0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8de0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8df0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8e10: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8e20: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8e30: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8e40: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8e50: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8e60: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8e70: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8e80: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8e90: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8ea0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8eb0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8ec0: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8ee0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8ef0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
8f00: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
8f10: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
8f20: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
8f30: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
8f40: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
8f50: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
8f60: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
8f70: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
8f80: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
8f90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
8fa0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
8fb0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
8fc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
8fd0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
8fe0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
8ff0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9000: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9010: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9020: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9030: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9040: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9050: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9060: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9070: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9080: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9090: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
90a0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
90b0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
90c0: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
90d0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
90e0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
90f0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9100: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9110: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9120: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9130: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9140: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9150: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9160: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9170: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9180: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9190: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
91a0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
91b0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
91c0: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
91d0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
91e0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
91f0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9200: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9210: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9220: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9230: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9240: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9250: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9260: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9270: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9280: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9290: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
92a0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
92b0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
92c0: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
92d0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
92e0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
92f0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9300: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9310: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9320: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9330: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9340: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9350: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9360: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9370: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9380: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9390: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
93a0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
93b0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
93c0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
93d0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
93e0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
93f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9410: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9420: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9440: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9450: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9460: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9470: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9480: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9490: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
94a0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
94b0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
94c0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
94d0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
94e0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
94f0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9500: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9510: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9520: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9530: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9540: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9550: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9560: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9570: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9580: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
9590: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
95a0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
95b0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
95c0: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
95d0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
95e0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
95f0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9600: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9610: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9620: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9630: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9640: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9650: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9660: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9670: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9680: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9690: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
96a0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
96b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
96c0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
96d0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
96e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
96f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9700: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9710: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9720: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9730: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9740: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9750: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9760: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
9770: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9780: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9790: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
97a0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
97b0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
97c0: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
97d0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
97e0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
97f0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9800: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9810: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9820: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9830: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9840: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9850: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
9860: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
9870: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
9880: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
9890: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
98a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
98b0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
98c0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
98d0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
98e0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
98f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9900: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9910: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9920: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9930: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9940: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9950: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
9960: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
9970: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
9980: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
9990: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
99a0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
99b0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
99c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
99d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
99e0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
99f0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9a00: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9a10: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9a20: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9a30: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9a40: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9a50: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9a60: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9a70: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9a80: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9a90: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9aa0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9ab0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9ac0: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9ad0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9ae0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9af0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9b00: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9b10: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9b20: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9b30: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9b40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9b50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9b60: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9b70: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9b80: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9b90: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9ba0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9bb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9bc0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9bd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9be0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9bf0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9c00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9c10: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9c20: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9c30: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9c40: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9c50: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9c60: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9c70: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9c80: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9c90: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9ca0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9cb0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9cc0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9cd0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9ce0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9cf0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9d00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9d10: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9d20: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9d30: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9d40: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9d50: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9d60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9d70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9d80: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9d90: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9da0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9db0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9dc0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9dd0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9de0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9df0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9e00: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9e10: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9e20: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9e30: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9e40: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9e50: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9e60: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9e70: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9e80: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9e90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9ea0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9eb0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9ec0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9ed0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9ee0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9ef0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
9f00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
9f10: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
9f20: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
9f30: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
9f40: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
9f50: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
9f60: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
9f70: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
9f80: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
9f90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
9fa0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9fb0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9fc0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
9fd0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
9fe0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
9ff0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a000: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a010: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a020: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a030: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a040: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a050: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a060: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a070: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a080: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a090: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a0a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a0b0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a0c0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a0d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a0e0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a0f0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a100: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a110: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a120: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a130: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f  tatements..** </
a140: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ul>.**.** <li>[[
a150: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
a160: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
a170: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a180: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
a190: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
a1a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
a1b0: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
a1c0: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
a1d0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
a1e0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
a1f0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
a200: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
a210: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
a220: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
a230: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
a240: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
a250: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
a260: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
a270: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
a280: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
a290: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
a2a0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
a2b0: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
a2c0: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
a2d0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
a2e0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
a2f0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
a300: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
a310: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
a320: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
a330: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
a340: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
a350: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
a360: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
a370: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
a380: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
a390: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
a3a0: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
a3b0: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
a3c0: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
a3d0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
a3e0: 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ion..*/.#define 
a3f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
a400: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
a410: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
a420: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
a430: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20  OXYFILE         
a440: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
a450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
a460: 58 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20  XYFILE          
a470: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
a480: 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20  ITE_LAST_ERRNO  
a490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a4a0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
a4b0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
a4c0: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
a4d0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
a4e0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
a4f0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
a500: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
a510: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
a520: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
a530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a540: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
a550: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
a560: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a570: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
a580: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
a590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a5a0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
a5b0: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
a5c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a5d0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
a5e0: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
a5f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
a600: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
a610: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
a620: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a630: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a640: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
a650: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a660: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
a670: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
a680: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
a690: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
a6a0: 20 20 20 20 20 20 31 35 0a 0a 2f 2a 0a 2a 2a 20        15../*.** 
a6b0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
a6c0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
a6d0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
a6e0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
a6f0: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
a700: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
a710: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
a720: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
a730: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
a740: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
a750: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
a760: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
a770: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
a780: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
a790: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
a7a0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
a7b0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
a7c0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
a7d0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
a7e0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
a7f0: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
a800: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
a810: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
a820: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
a830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a840: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
a850: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
a860: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
a870: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a880: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a890: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
a8a0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
a8b0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
a8c0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
a8d0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
a8e0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
a8f0: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
a900: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
a910: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
a920: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
a930: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
a940: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
a950: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
a960: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
a970: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
a980: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
a990: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
a9a0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
a9b0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
a9c0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
a9d0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
a9e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
a9f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
aa00: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
aa10: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
aa20: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
aa30: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
aa40: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
aa50: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
aa60: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
aa70: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
aa80: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
aa90: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
aaa0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
aab0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
aac0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
aad0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
aae0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
aaf0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
ab00: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
ab10: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
ab20: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
ab30: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
ab40: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
ab50: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
ab60: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
ab70: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
ab80: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
ab90: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
aba0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
abb0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
abc0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
abd0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
abe0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
abf0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
ac00: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
ac10: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
ac20: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
ac30: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
ac40: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
ac50: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
ac60: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
ac70: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
ac80: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
ac90: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
aca0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
acb0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
acc0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
acd0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ace0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
acf0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
ad00: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ad10: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
ad20: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
ad30: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
ad40: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
ad50: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
ad60: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
ad70: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
ad80: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
ad90: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
ada0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
adb0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
adc0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
add0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
ade0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
adf0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
ae00: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
ae10: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
ae20: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
ae30: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
ae40: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
ae50: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
ae60: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
ae70: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
ae80: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
ae90: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
aea0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
aeb0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
aec0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
aed0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
aee0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
aef0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
af00: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
af10: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
af20: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
af30: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
af40: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
af50: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
af60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
af70: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
af80: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
af90: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
afa0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
afb0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
afc0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
afd0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
afe0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
aff0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
b000: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
b010: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
b020: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
b030: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
b040: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
b050: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
b060: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
b070: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
b080: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
b090: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
b0a0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
b0b0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
b0c0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
b0d0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
b0e0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
b0f0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b100: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
b110: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
b120: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
b130: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
b140: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
b150: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
b160: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
b170: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
b180: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
b190: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
b1a0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
b1b0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
b1c0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
b1d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b1e0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
b1f0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b200: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
b210: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
b220: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
b230: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
b240: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
b250: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
b260: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
b270: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
b280: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
b290: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
b2a0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
b2b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
b2c0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
b2d0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
b2e0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
b2f0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
b300: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
b310: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
b320: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
b330: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
b340: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
b350: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
b360: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
b370: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
b380: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
b390: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
b3a0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
b3b0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
b3c0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
b3d0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
b3e0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
b3f0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
b400: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
b410: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b420: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
b430: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b440: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
b450: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b460: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
b470: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b480: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
b490: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
b4a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
b4b0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
b4c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
b4d0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
b4e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
b4f0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
b500: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
b510: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
b520: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
b530: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
b540: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
b550: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
b560: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
b570: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
b580: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
b590: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
b5a0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
b5b0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
b5c0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
b5d0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
b5e0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
b5f0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
b600: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
b610: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
b620: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
b630: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
b640: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
b650: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
b660: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
b670: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
b680: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
b690: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
b6a0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
b6b0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
b6c0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
b6d0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
b6e0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
b6f0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
b700: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
b710: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
b720: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
b730: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
b740: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
b750: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b760: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
b770: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
b780: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b790: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
b7a0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b7b0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
b7c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
b7d0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b7e0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
b7f0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
b800: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
b810: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
b820: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b830: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
b840: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
b850: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
b860: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
b870: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
b880: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
b890: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
b8a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b8b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
b8c0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
b8d0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
b8e0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
b8f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
b900: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
b910: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
b920: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
b930: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
b940: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
b950: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
b960: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
b970: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
b980: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
b990: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
b9a0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
b9b0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
b9c0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
b9d0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
b9e0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
b9f0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
ba00: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
ba10: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
ba20: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
ba30: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
ba40: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
ba50: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
ba60: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
ba70: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
ba80: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
ba90: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
baa0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
bab0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
bac0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
bad0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
bae0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
baf0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
bb00: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
bb10: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
bb20: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
bb30: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
bb40: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
bb50: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
bb60: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
bb70: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
bb80: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
bb90: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bba0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
bbb0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
bbc0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bbd0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
bbe0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
bbf0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
bc00: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
bc10: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
bc20: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
bc30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
bc40: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
bc50: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
bc60: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
bc70: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
bc80: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
bc90: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
bca0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
bcb0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
bcc0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
bcd0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
bce0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
bcf0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
bd00: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
bd10: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
bd20: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
bd30: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
bd40: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
bd50: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
bd60: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
bd70: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
bd80: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
bd90: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
bda0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
bdb0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
bdc0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
bdd0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
bde0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
bdf0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
be00: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
be10: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
be20: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
be30: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
be40: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
be50: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
be60: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
be70: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
be80: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
be90: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
bea0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
beb0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
bec0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
bed0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
bee0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
bef0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
bf00: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
bf10: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
bf20: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
bf30: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
bf40: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
bf50: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
bf60: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
bf70: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
bf80: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
bf90: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
bfa0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
bfb0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
bfc0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
bfd0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
bfe0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
bff0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
c000: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
c010: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
c020: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
c030: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
c040: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
c050: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
c060: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
c070: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
c080: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
c090: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
c0a0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
c0b0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
c0c0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
c0d0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
c0e0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
c0f0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
c100: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
c110: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
c120: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
c130: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
c140: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
c150: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
c160: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
c170: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
c180: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
c190: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
c1a0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
c1b0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
c1c0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
c1d0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
c1e0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
c1f0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
c200: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
c210: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c220: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
c230: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
c240: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
c250: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
c260: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
c270: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
c280: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
c290: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
c2a0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
c2b0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
c2c0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
c2d0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
c2e0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
c2f0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
c300: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
c310: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
c320: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
c330: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
c340: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
c350: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
c360: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
c370: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
c380: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
c390: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
c3a0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
c3b0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
c3c0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
c3d0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
c3e0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
c3f0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
c400: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
c410: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
c420: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
c430: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
c440: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
c450: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
c460: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
c470: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
c480: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
c490: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
c4a0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
c4b0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
c4c0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
c4d0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
c4e0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
c4f0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
c500: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
c510: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
c520: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
c530: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
c540: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
c550: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
c560: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
c570: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
c580: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
c590: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
c5a0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
c5b0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
c5c0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
c5d0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
c5e0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
c5f0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
c600: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
c610: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
c620: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
c630: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
c640: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
c650: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
c660: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
c670: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
c680: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
c690: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
c6a0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
c6b0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
c6c0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
c6d0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
c6e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
c6f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
c700: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
c710: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c720: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
c730: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
c740: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
c750: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
c760: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
c770: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
c780: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
c790: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
c7a0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
c7b0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
c7c0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
c7d0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
c7e0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
c7f0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
c800: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
c810: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
c820: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
c830: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
c840: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
c850: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
c860: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
c870: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
c880: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
c890: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
c8a0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
c8b0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
c8c0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
c8d0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c8e0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c8f0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
c900: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
c910: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
c920: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
c930: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
c940: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c950: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
c960: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
c970: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(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 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
c9b0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
c9c0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
c9d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c9e0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
c9f0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
ca00: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
ca10: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
ca20: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ca30: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
ca40: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
ca50: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
ca60: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ca70: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
ca80: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
ca90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
caa0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
cab0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
cac0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
cad0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
cae0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
caf0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
cb00: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
cb10: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
cb20: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
cb30: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
cb40: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
cb50: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
cb60: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
cb70: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
cb80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
cb90: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
cba0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
cbb0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
cbc0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
cbd0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
cbe0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
cbf0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
cc00: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
cc10: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
cc20: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
cc30: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
cc40: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
cc50: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
cc60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
cc70: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
cc80: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
cc90: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
cca0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ccb0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
ccc0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ccd0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
cce0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ccf0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
cd00: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
cd10: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
cd20: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
cd30: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
cd40: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
cd50: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
cd60: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
cd70: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
cd80: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
cd90: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
cda0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
cdb0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
cdc0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
cdd0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
cde0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
cdf0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ce00: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ce10: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ce20: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ce30: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ce40: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ce50: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
ce60: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ce70: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ce80: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ce90: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
cea0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ceb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
cec0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ced0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
cee0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cef0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
cf00: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
cf10: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
cf20: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
cf30: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
cf40: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
cf50: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
cf60: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
cf70: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
cf80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
cf90: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
cfa0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
cfb0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
cfc0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
cfd0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
cfe0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
cff0: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
d000: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
d010: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
d020: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d030: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d040: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
d050: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
d060: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d070: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
d080: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
d090: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
d0a0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
d0b0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
d0c0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
d0d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
d0e0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
d0f0: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
d100: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
d110: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
d120: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
d130: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
d140: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
d150: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
d160: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
d170: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
d180: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
d190: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
d1a0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
d1b0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
d1c0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
d1d0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d1e0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
d1f0: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
d200: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
d210: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
d220: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
d230: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
d240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d250: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
d260: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
d270: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d280: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
d290: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
d2a0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
d2b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
d2c0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
d2d0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
d2e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d2f0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d300: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
d310: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
d320: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d330: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
d340: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
d350: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
d360: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
d370: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
d380: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d390: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
d3a0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
d3b0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
d3c0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
d3d0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
d3e0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
d3f0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
d400: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
d410: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
d420: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d430: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
d440: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
d450: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
d460: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
d470: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
d480: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
d490: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
d4a0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
d4b0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
d4c0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
d4d0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
d4e0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
d4f0: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
d500: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
d510: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
d520: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
d530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
d540: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
d550: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
d560: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
d570: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
d580: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
d590: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
d5a0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
d5b0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
d5c0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
d5d0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
d5e0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d5f0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
d600: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
d610: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
d620: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
d630: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
d640: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
d650: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
d660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
d670: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
d680: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
d690: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d6a0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
d6b0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
d6c0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
d6d0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
d6e0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
d6f0: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
d700: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
d710: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
d720: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
d730: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
d740: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
d750: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
d760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
d770: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
d780: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
d790: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
d7a0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
d7b0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
d7c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d7d0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
d7e0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
d7f0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
d800: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
d810: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
d820: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
d830: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
d840: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
d850: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
d860: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
d870: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
d880: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
d890: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
d8a0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
d8b0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
d8c0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
d8d0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
d8e0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
d8f0: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
d900: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
d910: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
d920: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
d930: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
d940: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
d950: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
d960: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
d970: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
d980: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
d990: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
d9a0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
d9b0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
d9c0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
d9d0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
d9e0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
d9f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
da00: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
da10: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
da20: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
da30: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
da40: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
da50: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
da60: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
da70: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
da80: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
da90: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
daa0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
dab0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
dac0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dad0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
dae0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
daf0: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
db00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
db10: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
db20: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
db30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
db40: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
db50: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
db60: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
db70: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
db80: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
db90: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
dba0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
dbb0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
dbc0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
dbd0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
dbe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dbf0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
dc00: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
dc10: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dc20: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
dc30: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
dc40: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
dc50: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
dc60: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
dc70: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
dc80: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
dc90: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
dca0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
dcb0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
dcc0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
dcd0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
dce0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
dcf0: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
dd00: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
dd10: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
dd20: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
dd30: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
dd40: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
dd50: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
dd60: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
dd70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
dd80: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
dd90: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
dda0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
ddb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
ddc0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
ddd0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
dde0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
ddf0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
de00: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
de10: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
de20: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
de30: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
de40: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
de50: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
de60: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
de70: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
de80: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
de90: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
dea0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
deb0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
dec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ded0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
dee0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
def0: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
df00: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
df10: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
df20: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
df30: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
df40: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
df50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
df60: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
df70: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
df80: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
df90: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
dfa0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
dfb0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
dfc0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
dfd0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
dfe0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
dff0: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
e000: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
e010: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
e020: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
e030: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
e040: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e050: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
e060: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
e070: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
e080: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
e090: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
e0a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
e0b0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
e0c0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
e0d0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
e0e0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
e0f0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e100: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
e110: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e120: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e130: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
e140: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
e150: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
e160: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
e170: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
e180: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e190: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
e1a0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
e1b0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
e1c0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
e1d0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
e1e0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
e1f0: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
e200: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
e210: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
e220: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
e230: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e240: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
e250: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
e260: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
e270: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
e280: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
e290: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e2a0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
e2b0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
e2c0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
e2d0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
e2e0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
e2f0: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
e300: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
e310: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
e320: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
e330: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
e340: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
e350: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
e360: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
e370: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
e380: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
e390: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
e3a0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
e3b0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
e3c0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
e3d0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
e3e0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
e3f0: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
e400: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
e410: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
e420: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
e430: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
e440: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
e450: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
e460: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
e470: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
e480: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
e490: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
e4a0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
e4b0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
e4c0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
e4d0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
e4e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
e4f0: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
e500: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
e510: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
e520: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
e530: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
e540: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
e550: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e560: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
e570: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
e580: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
e590: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
e5a0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
e5b0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
e5c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e5d0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
e5e0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
e5f0: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
e600: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
e610: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
e620: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
e630: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
e640: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
e650: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
e660: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
e670: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
e680: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
e690: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
e6a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
e6b0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
e6c0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
e6d0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
e6e0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
e6f0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e700: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
e710: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
e720: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
e730: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
e740: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
e750: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
e760: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
e770: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
e780: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
e790: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
e7a0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
e7b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e7c0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
e7d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
e7e0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
e7f0: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
e800: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
e810: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
e820: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e830: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
e840: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e850: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
e860: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
e870: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
e880: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
e890: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e8a0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
e8b0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
e8c0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
e8d0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
e8e0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
e8f0: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
e900: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
e910: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
e920: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
e930: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
e940: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
e950: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
e960: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
e970: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
e980: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
e990: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
e9a0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
e9b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
e9c0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
e9d0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
e9e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
e9f0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
ea00: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
ea10: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
ea20: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
ea30: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
ea40: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
ea50: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
ea60: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
ea70: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
ea80: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
ea90: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
eaa0: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
eab0: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
eac0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ead0: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
eae0: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
eaf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
eb00: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
eb10: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
eb20: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
eb30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
eb40: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
eb50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eb60: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
eb70: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
eb80: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
eb90: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
eba0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
ebb0: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
ebc0: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
ebd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ebe0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
ebf0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
ec00: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
ec10: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
ec20: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
ec30: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
ec40: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
ec50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
ec60: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
ec70: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
ec80: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
ec90: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
eca0: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
ecb0: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
ecc0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ecd0: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
ece0: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
ecf0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
ed00: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
ed10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ed20: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
ed30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
ed40: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ed50: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
ed60: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
ed70: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
ed80: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
ed90: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
eda0: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
edb0: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
edc0: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
edd0: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
ede0: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
edf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ee00: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
ee10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
ee20: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
ee30: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ee40: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ee50: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
ee60: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
ee70: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
ee80: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
ee90: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
eea0: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
eeb0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
eec0: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
eed0: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
eee0: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
eef0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
ef00: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
ef10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
ef20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
ef30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
ef40: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ef50: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
ef60: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
ef70: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
ef80: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
ef90: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
efa0: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
efb0: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
efc0: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
efd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
efe0: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
eff0: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
f000: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
f010: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
f020: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
f030: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
f040: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
f050: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
f060: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
f070: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
f080: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
f090: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
f0a0: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
f0b0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
f0c0: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
f0d0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
f0e0: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
f0f0: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
f100: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
f110: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f120: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
f130: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
f140: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
f150: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
f160: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
f170: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
f180: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
f190: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
f1a0: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
f1b0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
f1c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
f1d0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
f1e0: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
f1f0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
f200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
f210: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
f220: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
f230: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
f240: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
f250: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f260: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
f270: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
f280: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
f290: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
f2a0: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
f2b0: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
f2c0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
f2d0: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
f2e0: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
f2f0: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
f300: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
f310: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
f320: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
f330: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
f340: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
f350: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
f360: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
f370: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
f380: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
f390: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
f3a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f3b0: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
f3c0: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
f3d0: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
f3e0: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
f3f0: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
f400: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
f410: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
f420: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
f430: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
f440: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
f450: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
f460: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f470: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
f480: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
f490: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
f4a0: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
f4b0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
f4c0: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
f4d0: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
f4e0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
f4f0: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
f500: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
f510: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
f520: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
f530: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
f540: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
f550: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
f560: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
f570: 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
f580: 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
f590: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
f5a0: 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
f5b0: 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
f5c0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
f5d0: 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
f5e0: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
f5f0: 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
f600: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
f610: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
f620: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
f630: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
f640: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
f650: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
f660: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
f670: 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
f680: 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
f690: 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
f6a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
f6b0: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
f6c0: 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
f6d0: 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
f6e0: 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
f6f0: 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
f700: 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
f710: 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
f720: 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
f730: 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
f740: 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
f750: 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
f760: 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
f770: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
f780: 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
f790: 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
f7a0: 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
f7b0: 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
f7c0: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f7d0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
f7e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
f7f0: 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
f800: 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
f810: 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
f820: 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
f830: 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
f840: 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
f850: 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
f860: 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
f870: 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
f880: 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
f890: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
f8a0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
f8b0: 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
f8c0: 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
f8d0: 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
f8e0: 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
f8f0: 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
f900: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
f910: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
f920: 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
f930: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
f940: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
f950: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
f960: 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
f970: 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
f980: 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
f990: 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
f9a0: 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
f9b0: 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
f9c0: 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
f9d0: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
f9e0: 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
f9f0: 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
fa00: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
fa10: 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
fa20: 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
fa30: 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
fa40: 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
fa50: 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
fa60: 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
fa70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
fa80: 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
fa90: 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
faa0: 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
fab0: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
fac0: 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
fad0: 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
fae0: 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
faf0: 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
fb00: 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
fb10: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
fb20: 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
fb30: 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
fb40: 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
fb50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fb60: 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
fb70: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
fb80: 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
fb90: 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
fba0: 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
fbb0: 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
fbc0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
fbd0: 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
fbe0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
fbf0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
fc00: 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
fc10: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fc20: 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
fc30: 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
fc40: 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
fc50: 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
fc60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
fc70: 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
fc80: 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
fc90: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
fca0: 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
fcb0: 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
fcc0: 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
fcd0: 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
fce0: 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
fcf0: 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
fd00: 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
fd10: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
fd20: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
fd30: 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
fd40: 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
fd50: 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
fd60: 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
fd70: 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
fd80: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fd90: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fda0: 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
fdb0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
fdc0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
fdd0: 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
fde0: 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
fdf0: 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
fe00: 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
fe10: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
fe20: 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
fe30: 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
fe40: 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
fe50: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
fe60: 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
fe70: 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
fe80: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
fe90: 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
fea0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
feb0: 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
fec0: 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
fed0: 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
fee0: 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
fef0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
ff00: 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
ff10: 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
ff20: 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
ff30: 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
ff40: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
ff50: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
ff60: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
ff70: 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
ff80: 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
ff90: 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
ffa0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
ffb0: 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
ffc0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
ffd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
ffe0: 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
fff0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
10000 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
10010 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10020 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
10030 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
10040 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10050 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
10060 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
10070 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
10080 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
10090 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
100a0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
100b0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
100c0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
100d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
100e0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
100f0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10100 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10110 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10120 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10130 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
10140 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10150 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
10160 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
10170 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
10180 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
10190 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
101a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
101b0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
101c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
101d0 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
101e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
101f0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
10200 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
10210 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10220 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
10230 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
10240 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
10250 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
10260 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
10270 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
10280 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10290 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
102a0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
102b0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
102c0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
102d0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
102e0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
102f0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10300 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10310 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
10320 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
10330 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
10340 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
10350 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
10360 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
10370 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
10380 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
10390 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
103a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
103b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
103c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
103d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
103e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
103f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10400 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10410 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
10420 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
10430 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
10440 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
10450 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
10460 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
10470 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10480 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
10490 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
104a0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
104b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
104c0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
104d0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
104e0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
104f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10500 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
10510 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10520 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
10530 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10540 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10550 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10560 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10570 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10580 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
10590 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
105a0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
105b0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
105c0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
105d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
105e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
105f0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
10600 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
10610 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
10620 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
10630 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
10640 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10650 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
10660 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
10670 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
10680 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
10690 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
106a0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
106b0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
106c0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
106d0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
106e0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
106f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
10700 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
10710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10720 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
10730 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
10740 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10750 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10760 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10770 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10780 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10790 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
107a0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
107b0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
107c0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
107d0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
107e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
107f0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
10800 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
10810 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
10820 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
10830 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
10840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10850 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
10860 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10870 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
10880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10890 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
108a0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
108b0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
108c0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
108d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
108e0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
108f0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
10900 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
10910 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
10920 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
10930 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
10940 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
10950 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
10960 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10970 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
10980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
10990 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
109a0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
109b0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
109c0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
109d0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
109e0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
109f0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
10a00 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
10a10 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
10a20 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
10a30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10a40 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
10a50 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
10a60 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
10a70 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
10a80 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
10a90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10aa0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
10ab0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
10ac0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
10ad0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
10ae0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10af0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
10b00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
10b10 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
10b20 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
10b30 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
10b40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
10b50 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
10b60 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
10b70 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
10b80 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
10b90 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10ba0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10bb0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
10bc0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10bd0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10be0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10bf0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
10c00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
10c10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10c30 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
10c40 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
10c50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
10c60 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
10c70 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
10c80 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
10c90 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
10ca0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
10cb0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10cc0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
10cd0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
10ce0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
10cf0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
10d00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10d10 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
10d20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
10d30 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
10d40 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
10d50 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10d60 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
10d70 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
10d80 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
10d90 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
10da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
10db0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
10dc0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
10dd0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10de0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
10df0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
10e00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10e10 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
10e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10e30 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
10e40 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10e50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
10e60 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
10e70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
10e80 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
10e90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
10ea0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
10eb0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
10ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
10ed0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
10ee0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
10ef0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
10f00 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
10f10 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
10f20 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
10f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
10f40 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
10f50 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
10f60 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
10f70 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
10f80 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
10f90 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
10fa0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
10fb0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
10fc0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
10fd0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
10fe0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
10ff0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
11000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
11010 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
11020 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11030 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
11040 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
11050 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
11060 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
11070 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
11080 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
11090 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
110a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110b0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
110c0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
110d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
110e0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
110f0 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
11100 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
11110 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
11120 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
11130 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
11140 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
11150 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
11160 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
11170 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
11180 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11190 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
111a0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
111b0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
111c0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
111d0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
111e0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
111f0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
11200 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
11210 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
11220 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
11230 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
11240 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
11250 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
11260 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
11270 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
11280 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
11290 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
112a0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
112b0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
112c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
112d0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
112e0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
112f0 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
11300 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
11310 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
11320 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
11330 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
11340 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11350 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
11360 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
11370 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
11380 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
11390 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
113a0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
113b0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
113c0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
113d0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
113e0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
113f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11400 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
11410 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
11420 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
11430 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
11440 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
11450 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11460 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
11470 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
11480 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
11490 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
114a0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
114b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
114c0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
114d0 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
114e0 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
114f0 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
11500 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
11510 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
11520 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
11530 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
11540 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11550 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
11560 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
11570 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
11580 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
11590 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
115a0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
115b0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
115c0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
115d0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
115e0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
115f0 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
11600 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
11610 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
11620 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
11630 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
11640 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
11650 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11660 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
11670 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
11680 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
11690 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
116a0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
116b0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
116c0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
116d0 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
116e0 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
116f0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
11700 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
11710 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
11720 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
11730 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
11740 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
11750 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
11760 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
11770 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
11780 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
11790 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
117a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
117b0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
117c0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
117d0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
117e0 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
117f0 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
11800 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
11810 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
11820 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
11830 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
11840 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
11850 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
11860 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
11870 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
11880 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
11890 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
118a0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
118b0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
118c0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
118d0 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
118e0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
118f0 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
11900 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
11910 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
11920 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
11930 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
11940 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
11950 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
11960 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
11970 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
11980 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
11990 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
119a0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
119b0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
119c0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
119d0 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
119e0 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
119f0 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
11a00 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
11a10 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11a20 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
11a30 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
11a40 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
11a50 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
11a60 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
11a70 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
11a80 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
11a90 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
11aa0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
11ab0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
11ac0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
11ad0 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
11ae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
11af0 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
11b00 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
11b10 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
11b20 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11b30 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
11b40 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
11b50 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
11b60 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
11b70 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
11b80 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
11b90 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
11ba0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11bb0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
11bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
11bd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11be0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
11bf0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
11c00 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
11c10 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
11c20 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
11c30 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
11c40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
11c50 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
11c60 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
11c70 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
11c80 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
11c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
11ca0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
11cb0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
11cc0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
11cd0 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
11ce0 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
11cf0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
11d00 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
11d10 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
11d20 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11d30 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
11d40 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
11d50 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
11d60 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
11d70 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
11d80 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
11d90 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
11da0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11db0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
11dc0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
11dd0 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
11de0 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
11df0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
11e00 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
11e10 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
11e20 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
11e30 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
11e40 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
11e50 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
11e60 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
11e70 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
11e80 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
11e90 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
11ea0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
11eb0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
11ec0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
11ed0 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
11ee0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
11ef0 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
11f00 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
11f10 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
11f20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
11f30 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
11f40 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
11f50 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
11f60 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
11f70 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
11f80 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
11f90 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
11fa0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
11fb0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
11fc0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
11fd0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
11fe0 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
11ff0 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
12000 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12010 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
12020 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
12030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12040 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12050 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12060 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12070 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12080 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12090 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
120a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
120b0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
120c0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
120d0 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
120e0 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
120f0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12100 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
12110 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
12120 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12130 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12140 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12150 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
12160 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
12170 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12180 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
12190 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
121a0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
121b0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
121c0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
121d0 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
121e0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
121f0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12200 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12210 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
12220 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
12230 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
12240 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
12250 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
12260 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
12270 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
12280 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
12290 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
122a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
122b0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
122c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
122d0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
122e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
122f0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
12300 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
12310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12320 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12330 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12340 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12350 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
12360 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12370 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12380 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
12390 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
123a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
123b0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
123c0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
123d0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
123e0 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
123f0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
12400 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
12410 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
12420 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
12430 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12440 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12450 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
12460 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
12470 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
12480 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
12490 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
124a0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
124b0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
124c0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
124d0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
124e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
124f0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
12500 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
12510 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
12520 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
12530 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
12540 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
12550 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
12560 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12570 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
12580 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
12590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
125a0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
125b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
125c0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
125d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
125e0 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
125f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12600 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
12610 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12620 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12630 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
12640 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
12650 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
12660 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
12670 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
12680 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
12690 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
126a0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
126b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
126c0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
126d0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
126e0 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
126f0 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
12700 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
12710 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
12720 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
12730 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
12740 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
12750 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
12760 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
12770 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
12780 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
12790 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
127a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
127b0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
127c0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
127d0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
127e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
127f0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
12800 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
12810 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12820 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
12830 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12840 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
12850 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12860 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12870 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12880 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12890 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
128a0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
128b0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
128c0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
128d0 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
128e0 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
128f0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
12900 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
12910 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
12920 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
12930 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
12940 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
12950 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12960 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12980 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
12990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
129a0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
129b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
129c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
129d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
129e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
129f0 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
12a00 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
12a10 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
12a20 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
12a30 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
12a40 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12a50 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
12a60 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
12a70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12a80 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
12a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
12aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12ab0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12ac0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
12ad0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
12ae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
12af0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
12b00 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
12b10 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
12b20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
12b30 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
12b40 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
12b50 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
12b60 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
12b70 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
12b80 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
12b90 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
12ba0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
12bb0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
12bc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
12bd0 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
12be0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
12bf0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
12c00 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
12c10 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
12c20 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
12c30 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12c40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
12c50 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
12c60 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
12c70 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
12c80 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
12c90 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
12ca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
12cb0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
12cc0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
12cd0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
12ce0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
12cf0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
12d00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
12d10 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
12d20 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
12d30 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
12d40 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
12d50 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
12d60 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
12d70 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
12d80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12d90 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
12da0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
12db0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
12dc0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
12dd0 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
12de0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
12df0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
12e00 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
12e10 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
12e20 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
12e30 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12e40 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
12e50 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
12e60 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
12e70 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
12e80 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
12e90 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
12ea0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
12eb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12ec0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
12ed0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
12ee0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
12ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f00 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
12f10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12f20 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
12f30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12f40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12f50 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
12f60 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
12f70 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
12f80 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
12f90 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
12fa0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
12fb0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
12fc0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
12fd0 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
12fe0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
12ff0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
13000 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
13010 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
13020 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
13030 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
13040 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
13050 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
13060 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
13070 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
13080 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
13090 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
130a0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
130b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
130c0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
130d0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
130e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
130f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
13100 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
13110 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13120 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
13130 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
13140 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
13150 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
13160 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
13170 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
13180 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
13190 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
131a0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
131b0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
131c0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
131d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
131e0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
131f0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
13200 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
13210 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
13220 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
13230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
13240 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
13250 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13260 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
13270 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
13280 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b   This option tak
13290 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
132a0 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  er argument whic
132b0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
132c0 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e   as.** a boolean
132d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
132e0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
132f0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
13300 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a  ng indices for.*
13310 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  * full table sca
13320 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
13330 6f 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20  optimizer.  The 
13340 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
13350 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
13360 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
13370 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
13380 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
13390 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
133a0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
133b0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
133c0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
133d0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
133e0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
133f0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
13400 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
13410 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
13420 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
13430 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
13440 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
13450 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
13460 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  malfunction.** m
13470 61 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20  alfunction when 
13480 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
13490 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
134a0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
134b0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
134c0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
134d0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
134e0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
134f0 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
13500 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
13510 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
13520 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
13530 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
13540 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13550 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
13560 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13570 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
13580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13590 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
135a0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
135b0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
135c0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
135d0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
135e0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
135f0 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
13600 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
13610 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
13620 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
13630 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
13640 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
13650 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13660 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
13670 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
13680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13690 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
136a0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
136b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
136c0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
136d0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
136e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
136f0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
13700 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
13710 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
13720 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13730 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
13740 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
13750 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
13760 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13770 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
13780 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
13790 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
137a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
137b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
137c0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
137d0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
137e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
137f0 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
13800 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
13810 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
13820 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
13830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13840 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
13850 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
13860 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13870 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
13880 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
13890 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
138a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
138b0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
138c0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
138d0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
138e0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
138f0 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
13900 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
13910 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
13920 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
13930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
13940 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
13950 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
13960 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13970 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
13980 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
13990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
139a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
139b0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
139c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
139d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
139e0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
139f0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
13a00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13a10 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
13a20 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
13a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13a40 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
13a50 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
13a60 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
13a70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13a80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13a90 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
13aa0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
13ab0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
13ac0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
13ad0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
13ae0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
13af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13b00 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
13b10 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
13b20 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
13b30 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
13b40 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
13b50 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
13b60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13b70 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
13b80 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
13b90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13ba0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
13bb0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
13bc0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
13bd0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13be0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13bf0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13c00 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13c10 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13c20 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13c30 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13c40 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13c50 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13c60 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13c70 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
13c80 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13c90 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
13ca0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
13cb0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
13cc0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
13cd0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
13ce0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
13cf0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13d00 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
13d10 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
13d20 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
13d30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
13d40 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
13d50 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
13d60 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13d70 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
13d80 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
13d90 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
13da0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
13db0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
13dc0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
13dd0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
13de0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
13df0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
13e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13e10 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
13e20 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
13e30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
13e40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
13e50 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
13e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
13e70 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
13e80 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
13e90 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
13ea0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13eb0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
13ec0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13ed0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
13ee0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
13ef0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
13f00 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
13f10 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
13f20 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
13f30 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13f40 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
13f50 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
13f60 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
13f70 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
13f80 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
13f90 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
13fa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
13fb0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
13fc0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
13fd0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
13fe0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
13ff0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
14000 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
14010 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
14020 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
14030 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
14040 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
14050 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
14060 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
14070 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
14080 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
14090 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
140a0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
140b0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
140c0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
140d0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
140e0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
140f0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
14100 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
14110 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
14120 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
14130 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
14140 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
14150 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
14160 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
14170 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
14180 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
14190 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
141a0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
141b0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
141c0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
141d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
141e0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
141f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14200 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
14210 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
14220 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
14230 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
14240 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
14250 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
14260 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
14270 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
14280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
14290 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
142a0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
142b0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
142c0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
142d0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
142e0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
142f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
14300 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
14310 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
14320 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
14330 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
14340 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
14350 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
14360 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
14370 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
14380 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
14390 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
143a0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
143b0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
143c0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
143d0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
143e0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
143f0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
14400 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
14410 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
14420 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14430 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14440 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
14450 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
14460 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
14470 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
14480 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
14490 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
144a0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
144b0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
144c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
144d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
144e0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
144f0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
14500 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
14510 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
14520 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
14530 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14540 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
14550 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
14560 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
14570 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14580 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
14590 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
145a0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
145b0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
145c0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
145d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
145e0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
145f0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
14600 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
14610 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
14620 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
14630 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
14640 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
14650 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
14660 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
14670 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
14680 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
14690 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
146a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
146b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
146c0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
146d0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
146e0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
146f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
14700 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14710 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
14720 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
14730 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
14740 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
14750 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
14760 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
14770 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
14780 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
14790 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
147a0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
147b0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
147c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
147d0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
147e0 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
147f0 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
14800 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
14810 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
14820 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
14830 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
14840 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
14850 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
14860 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
14870 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
14880 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
14890 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
148a0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
148b0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
148c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
148d0 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
148e0 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
148f0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
14900 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
14910 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14920 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
14930 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
14940 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
14950 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
14960 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
14970 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
14980 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
14990 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
149a0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
149b0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
149c0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
149d0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
149e0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
149f0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
14a00 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
14a10 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
14a20 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
14a30 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
14a40 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
14a50 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
14a60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
14a70 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
14a80 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
14a90 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
14aa0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
14ab0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
14ac0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
14ad0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
14ae0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
14af0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
14b00 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
14b10 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
14b20 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
14b30 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
14b40 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
14b50 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
14b60 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
14b70 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
14b80 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
14b90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
14ba0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
14bb0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
14bc0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
14bd0 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
14be0 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
14bf0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
14c00 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
14c10 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
14c20 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
14c30 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
14c40 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
14c50 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
14c60 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
14c70 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
14c80 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
14c90 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
14ca0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
14cb0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
14cc0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
14cd0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
14ce0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
14cf0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
14d00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
14d10 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
14d20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
14d30 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
14d40 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
14d50 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
14d60 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
14d70 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
14d80 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14d90 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
14da0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
14db0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
14dc0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
14dd0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
14de0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
14df0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
14e00 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
14e10 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
14e20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
14e30 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
14e40 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
14e50 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
14e60 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
14e70 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
14e80 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
14e90 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
14ea0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
14eb0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
14ec0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
14ed0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
14ee0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
14ef0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
14f00 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
14f10 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
14f20 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
14f30 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
14f40 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
14f50 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
14f60 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
14f70 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
14f80 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
14f90 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
14fa0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
14fb0 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
14fc0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
14fd0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
14fe0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
14ff0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
15000 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
15010 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
15020 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
15030 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
15040 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
15050 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
15060 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
15070 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
15080 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
15090 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
150a0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
150b0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
150c0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
150d0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
150e0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
150f0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
15100 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
15110 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
15120 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
15130 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15140 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15150 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
15160 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
15170 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
15180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15190 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
151a0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
151b0 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
151c0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
151d0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
151e0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
151f0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
15200 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
15210 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
15220 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
15230 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
15240 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
15250 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
15260 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
15270 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
15280 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
15290 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
152a0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
152b0 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
152c0 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
152d0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
152e0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
152f0 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
15300 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
15310 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
15320 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
15330 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
15340 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
15350 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
15360 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
15370 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
15380 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
15390 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
153a0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
153b0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
153c0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
153d0 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
153e0 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
153f0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
15400 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
15410 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
15420 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
15430 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
15440 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
15450 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
15460 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
15470 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
15480 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
15490 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
154a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
154b0 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
154c0 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
154d0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
154e0 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
154f0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
15500 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
15510 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
15520 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
15530 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
15540 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
15550 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
15560 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
15570 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
15580 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
15590 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
155a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
155b0 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
155c0 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
155d0 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
155e0 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
155f0 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
15600 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
15610 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
15620 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
15630 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
15640 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
15650 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
15660 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
15670 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
15680 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
15690 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
156a0 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
156b0 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
156c0 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
156d0 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
156e0 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
156f0 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
15700 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
15710 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
15720 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
15730 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
15740 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
15750 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
15760 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
15770 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
15780 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
15790 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
157a0 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
157b0 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
157c0 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
157d0 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
157e0 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
157f0 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
15800 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
15810 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
15820 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
15830 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
15840 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
15850 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
15860 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
15870 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
15880 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
15890 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
158a0 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
158b0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
158c0 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
158d0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
158e0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
158f0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15900 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
15910 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
15920 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
15930 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
15940 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
15950 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
15960 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
15970 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
15980 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
15990 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
159a0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
159b0 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
159c0 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
159d0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
159e0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
159f0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
15a00 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
15a10 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
15a20 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
15a30 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
15a40 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
15a50 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
15a60 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
15a70 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
15a80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
15a90 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
15aa0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
15ab0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
15ac0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
15ad0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
15ae0 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
15af0 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
15b00 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
15b10 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
15b20 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
15b30 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
15b40 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
15b50 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
15b60 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
15b70 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
15b80 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
15b90 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
15ba0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
15bb0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
15bc0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
15bd0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
15be0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
15bf0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
15c00 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
15c10 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
15c20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
15c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
15c40 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15c50 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
15c60 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
15c70 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
15c80 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
15c90 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
15ca0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
15cb0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
15cc0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
15cd0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
15ce0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15cf0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15d00 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15d10 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15d20 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
15d30 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
15d40 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
15d50 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
15d60 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
15d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15d80 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
15d90 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
15da0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15db0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
15dc0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
15dd0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
15de0 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
15df0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
15e00 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
15e10 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
15e20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15e30 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
15e40 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
15e50 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
15e60 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
15e70 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
15e80 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
15e90 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
15ea0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
15eb0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
15ec0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
15ed0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
15ee0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
15ef0 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
15f00 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
15f10 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
15f20 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
15f30 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
15f40 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
15f50 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
15f60 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
15f70 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
15f80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
15f90 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
15fa0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
15fb0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
15fc0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
15fd0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
15fe0 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
15ff0 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
16000 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
16010 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
16020 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
16030 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
16040 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
16050 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
16060 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
16070 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
16080 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
16090 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
160a0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
160b0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
160c0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
160d0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
160e0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
160f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
16100 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
16110 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
16120 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
16130 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
16140 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
16150 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
16160 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
16170 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
16180 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
16190 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
161a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
161b0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
161c0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
161d0 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
161e0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
161f0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
16200 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
16210 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
16220 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
16230 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
16240 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
16250 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
16260 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
16270 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
16280 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
16290 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
162a0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
162b0 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
162c0 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
162d0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
162e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
162f0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
16300 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
16310 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
16320 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
16330 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
16340 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
16350 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
16360 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
16370 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
16380 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
16390 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
163a0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
163b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
163c0 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
163d0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
163e0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
163f0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
16400 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
16410 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
16420 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
16430 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
16440 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
16450 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
16460 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
16470 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
16480 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
16490 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
164a0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
164b0 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
164c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
164d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
164e0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
164f0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
16500 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
16510 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
16520 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
16530 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
16540 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16550 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
16560 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
16570 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
16580 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
16590 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
165a0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
165b0 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
165c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
165d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
165e0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
165f0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
16600 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
16610 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
16620 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
16630 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
16640 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
16650 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16660 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
16670 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
16680 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16690 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
166a0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
166b0 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
166c0 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
166d0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
166e0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
166f0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
16700 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16710 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
16720 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
16730 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
16740 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
16750 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
16760 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
16770 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
16780 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
16790 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
167a0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
167b0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
167c0 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
167d0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
167e0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
167f0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
16800 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
16810 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
16820 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
16830 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
16840 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
16850 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16860 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
16870 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
16880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16890 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
168a0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
168b0 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
168c0 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
168d0 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
168e0 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
168f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16900 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
16910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
16920 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
16930 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
16940 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
16950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
16960 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
16970 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
16980 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
16990 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
169a0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
169b0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
169c0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
169d0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
169e0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
169f0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
16a00 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
16a10 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
16a20 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
16a30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16a40 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
16a50 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
16a60 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
16a70 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
16a80 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
16a90 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
16aa0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
16ab0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
16ac0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
16ad0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
16ae0 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
16af0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
16b00 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
16b10 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
16b20 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
16b30 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
16b40 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
16b50 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
16b60 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
16b70 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
16b80 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
16b90 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
16ba0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
16bb0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
16bc0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
16bd0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
16be0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
16bf0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
16c00 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
16c10 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
16c20 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
16c30 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
16c40 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
16c50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
16c60 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
16c70 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
16c80 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
16c90 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
16ca0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
16cb0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
16cc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
16cd0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
16ce0 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
16cf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
16d00 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
16d10 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
16d20 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
16d30 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
16d40 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
16d50 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
16d60 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
16d70 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
16d80 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
16d90 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
16da0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
16db0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
16dc0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
16dd0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
16de0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
16df0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
16e00 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
16e10 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
16e20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
16e30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
16e40 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
16e50 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
16e60 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
16e70 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
16e80 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
16e90 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
16ea0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
16eb0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
16ec0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
16ed0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
16ee0 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
16ef0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
16f00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
16f10 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
16f20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
16f30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
16f40 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
16f50 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
16f60 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
16f70 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
16f80 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
16f90 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
16fa0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
16fb0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
16fc0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
16fd0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
16fe0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
16ff0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
17000 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
17010 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
17020 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
17030 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
17040 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
17050 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
17060 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
17070 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
17080 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
17090 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
170a0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
170b0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
170c0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
170d0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
170e0 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
170f0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
17100 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
17110 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
17120 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
17130 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
17140 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
17150 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
17160 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
17170 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
17180 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
17190 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
171a0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
171b0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
171c0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
171d0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
171e0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
171f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
17200 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
17210 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
17220 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
17230 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
17240 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
17250 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
17260 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
17270 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
17280 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
17290 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
172a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
172b0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
172c0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
172d0 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
172e0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
172f0 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
17300 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
17310 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
17320 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
17330 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
17340 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
17350 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
17360 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
17370 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
17380 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
17390 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
173a0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
173b0 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
173c0 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
173d0 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
173e0 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
173f0 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
17400 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
17410 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
17420 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17430 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
17440 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
17450 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
17460 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
17470 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
17480 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
17490 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
174a0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
174b0 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
174c0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
174d0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
174e0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
174f0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
17500 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
17510 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
17520 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
17530 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
17540 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
17550 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
17560 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
17570 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
17580 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
17590 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
175a0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
175b0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
175c0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
175d0 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
175e0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
175f0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
17600 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
17610 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
17620 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
17630 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
17640 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
17650 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
17660 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
17670 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
17680 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
17690 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
176a0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
176b0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
176c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
176d0 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
176e0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
176f0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
17700 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
17710 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
17720 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
17730 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
17740 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
17750 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
17760 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
17770 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
17780 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
17790 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
177a0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
177b0 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
177c0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
177d0 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
177e0 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
177f0 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
17800 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
17810 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
17820 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
17830 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
17840 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
17850 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
17860 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
17870 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
17880 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
17890 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
178a0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
178b0 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
178c0 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
178d0 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
178e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
178f0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
17900 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
17910 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
17920 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
17930 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
17940 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
17950 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
17960 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
17970 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
17980 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
17990 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
179a0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
179b0 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
179c0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
179d0 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
179e0 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
179f0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
17a00 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
17a10 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
17a20 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
17a30 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
17a40 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
17a50 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
17a60 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
17a70 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
17a80 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
17a90 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
17aa0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
17ab0 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
17ac0 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
17ad0 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
17ae0 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
17af0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
17b00 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
17b10 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
17b20 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
17b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17b40 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
17b50 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
17b60 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
17b70 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
17b80 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
17b90 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
17ba0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
17bb0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
17bc0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
17bd0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
17be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
17bf0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
17c00 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
17c10 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
17c20 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
17c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
17c40 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
17c50 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
17c60 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
17c70 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
17c80 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
17c90 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
17ca0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
17cb0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
17cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
17cd0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
17ce0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
17cf0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
17d00 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
17d10 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17d20 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
17d30 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
17d40 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17d50 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
17d60 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
17d70 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
17d80 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
17d90 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
17da0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
17db0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
17dc0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
17dd0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
17de0 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
17df0 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
17e00 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
17e10 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
17e20 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
17e30 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
17e40 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
17e50 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
17e60 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
17e70 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
17e80 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
17e90 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
17ea0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
17eb0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
17ec0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
17ed0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
17ee0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
17ef0 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
17f00 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
17f10 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
17f20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
17f30 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
17f40 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
17f50 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
17f60 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
17f70 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
17f80 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
17f90 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
17fa0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
17fb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
17fc0 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
17fd0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
17fe0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
17ff0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
18000 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
18010 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
18020 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
18030 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
18040 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
18050 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
18060 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ed.)^.*/.int sql
18070 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
18080 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
18090 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
180a0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
180b0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
180c0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
180d0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
180e0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
180f0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
18100 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
18110 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
18120 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
18130 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
18140 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
18150 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
18160 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
18170 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
18180 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
18190 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
181a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
181b0 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
181c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
181d0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
181e0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
181f0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
18200 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
18210 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
18220 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
18230 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
18240 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
18250 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
18260 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
18270 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
18280 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
18290 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
182a0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
182b0 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
182c0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
182d0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
182e0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
182f0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
18300 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
18310 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
18320 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
18330 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
18340 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
18350 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
18360 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
18370 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
18380 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
18390 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
183a0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
183b0 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
183c0 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
183d0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
183e0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
183f0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
18400 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
18410 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
18420 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
18430 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
18440 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
18450 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
18460 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
18470 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
18480 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
18490 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
184a0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
184b0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
184c0 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
184d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
184e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
184f0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
18500 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
18510 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
18520 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
18530 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
18540 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
18550 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
18560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
18570 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
18580 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
18590 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
185a0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
185b0 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
185c0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
185d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
185e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
185f0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
18600 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
18610 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
18620 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
18630 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
18640 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
18650 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
18660 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
18670 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
18680 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
18690 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
186a0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
186b0 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
186c0 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
186d0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
186e0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
186f0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
18700 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
18710 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
18720 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
18730 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
18740 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
18750 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
18760 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18770 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
18780 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
18790 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
187a0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
187b0 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
187c0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
187d0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
187e0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
187f0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
18800 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
18810 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
18820 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
18830 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
18840 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
18850 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18860 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
18870 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
18880 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
18890 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
188a0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
188b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
188c0 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
188d0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
188e0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
188f0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
18900 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
18910 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
18920 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
18930 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
18940 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
18950 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
18960 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
18970 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
18980 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
18990 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
189a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
189b0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
189c0 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
189d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
189e0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
189f0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
18a00 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
18a10 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
18a20 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
18a30 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
18a40 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
18a50 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
18a60 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
18a70 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
18a80 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
18a90 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
18aa0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
18ab0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
18ac0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
18ad0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
18ae0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
18af0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
18b00 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18b10 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
18b20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
18b30 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
18b40 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
18b50 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
18b60 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
18b70 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
18b80 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
18b90 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
18ba0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
18bb0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
18bc0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
18bd0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
18be0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
18bf0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
18c00 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
18c10 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
18c20 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
18c30 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
18c40 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
18c50 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
18c60 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
18c70 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
18c80 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
18c90 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
18ca0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
18cb0 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
18cc0 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
18cd0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
18ce0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
18cf0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
18d00 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
18d10 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
18d20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
18d30 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
18d40 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
18d50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
18d60 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
18d70 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
18d80 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
18d90 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
18da0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
18db0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
18dc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
18dd0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
18de0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
18df0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
18e00 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
18e10 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
18e20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
18e30 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
18e40 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
18e50 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
18e60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
18e70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
18e80 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
18e90 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
18ea0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
18eb0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
18ec0 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
18ed0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18ee0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
18ef0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
18f00 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
18f10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
18f20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
18f30 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
18f40 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
18f50 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
18f60 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
18f70 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
18f80 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
18f90 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
18fa0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
18fb0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
18fc0 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
18fd0 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
18fe0 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
18ff0 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
19000 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
19010 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
19020 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
19030 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
19040 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19050 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
19060 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
19070 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
19080 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
19090 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
190a0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
190b0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
190c0 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
190d0 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
190e0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
190f0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
19100 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
19110 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
19120 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
19130 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19140 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
19150 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
19160 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19170 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
19180 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
19190 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
191a0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
191b0 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
191c0 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
191d0 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
191e0 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
191f0 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
19200 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
19210 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
19220 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
19230 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
19240 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
19250 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
19260 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
19270 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
19280 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
19290 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
192a0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
192b0 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
192c0 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
192d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
192e0 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
192f0 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
19300 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
19310 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
19320 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
19330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
19340 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
19350 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
19360 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
19370 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
19380 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
19390 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
193a0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
193b0 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
193c0 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
193d0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
193e0 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
193f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
19400 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
19410 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
19420 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
19430 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
19440 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
19450 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
19460 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
19470 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
19480 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
19490 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
194a0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
194b0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
194c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
194d0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
194e0 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
194f0 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
19500 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
19510 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19520 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
19530 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
19540 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
19550 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
19560 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
19570 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
19580 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
19590 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
195a0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
195b0 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
195c0 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
195d0 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
195e0 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
195f0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
19600 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
19610 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
19620 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
19630 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
19640 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
19650 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
19660 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
19670 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
19680 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
19690 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
196a0 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
196b0 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
196c0 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
196d0 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
196e0 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
196f0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
19700 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
19710 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
19720 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
19730 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
19740 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
19750 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
19760 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
19770 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
19780 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
19790 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
197a0 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
197b0 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
197c0 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
197d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
197e0 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
197f0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
19800 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
19810 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
19820 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19830 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
19840 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
19850 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
19860 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
19870 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
19880 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
19890 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
198a0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
198b0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
198c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
198d0 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
198e0 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
198f0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
19900 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
19910 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
19920 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
19930 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
19940 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
19950 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
19960 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
19970 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
19980 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
19990 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
199a0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
199b0 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
199c0 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
199d0 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
199e0 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
199f0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
19a00 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
19a10 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
19a20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
19a30 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
19a40 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
19a50 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
19a60 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
19a70 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
19a80 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
19a90 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
19aa0 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
19ab0 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
19ac0 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
19ad0 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
19ae0 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
19af0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
19b00 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
19b10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
19b20 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
19b30 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
19b40 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
19b50 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
19b60 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
19b70 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
19b80 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
19b90 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
19ba0 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
19bb0 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
19bc0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
19bd0 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
19be0 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
19bf0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
19c00 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
19c10 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
19c20 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
19c30 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
19c40 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
19c50 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
19c60 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
19c70 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
19c80 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
19c90 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
19ca0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
19cb0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
19cc0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
19cd0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
19cf0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
19d00 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
19d10 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
19d20 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
19d30 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
19d40 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
19d50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
19d60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
19d70 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
19d80 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
19d90 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
19da0 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
19db0 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
19dc0 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
19dd0 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
19de0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
19df0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
19e00 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
19e10 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
19e20 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .*/.char *sqlite
19e30 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
19e40 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72  char*,...);.char
19e50 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
19e60 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
19e70 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a  va_list);.char *
19e80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
19e90 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
19ea0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68   char*, ...);.ch
19eb0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
19ec0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
19ed0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
19ee0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
19ef0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
19f00 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
19f10 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
19f20 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
19f30 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
19f40 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
19f50 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
19f60 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
19f70 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
19f80 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
19f90 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
19fa0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
19fb0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
19fc0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
19fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
19fe0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
19ff0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1a000 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1a010 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1a020 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1a030 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1a040 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1a050 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1a060 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1a070 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1a080 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1a090 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1a0a0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1a0b0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1a0c0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1a0d0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1a0e0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1a0f0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1a100 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1a110 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1a120 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1a130 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1a140 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1a150 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1a160 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1a170 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1a180 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1a190 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1a1a0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1a1b0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1a1c0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1a1d0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1a1e0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1a1f0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1a200 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1a210 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1a220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1a230 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1a240 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1a250 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1a260 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1a270 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1a280 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1a290 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1a2a0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1a2b0 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1a2c0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1a2d0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1a2e0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1a2f0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1a300 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1a310 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1a320 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1a330 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1a340 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1a350 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1a360 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1a370 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1a380 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1a390 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1a3a0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1a3b0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1a3c0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1a3d0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1a3e0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1a3f0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1a400 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1a410 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
1a420 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1a430 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
1a440 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1a450 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1a460 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1a470 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1a480 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
1a490 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
1a4a0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1a4b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a4c0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
1a4d0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1a4e0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
1a4f0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
1a500 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1a510 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1a520 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1a530 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1a540 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1a550 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1a560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1a570 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1a580 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a590 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1a5a0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
1a5b0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a5c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1a5d0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1a5e0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1a5f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1a600 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1a610 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1a620 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
1a630 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
1a640 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a650 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1a660 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
1a670 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1a680 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1a690 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1a6a0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1a6b0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1a6c0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1a6d0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1a6e0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
1a6f0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1a700 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1a710 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1a720 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1a730 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1a740 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1a750 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1a760 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1a770 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1a780 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1a790 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
1a7a0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1a7b0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1a7c0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1a7d0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
1a7e0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
1a7f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1a800 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1a810 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1a820 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a830 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
1a840 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a850 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1a860 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1a870 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1a880 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1a890 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1a8a0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1a8b0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1a8c0 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1a8d0 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1a8e0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1a8f0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1a900 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1a910 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1a920 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1a930 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1a940 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1a950 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1a960 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1a970 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1a980 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1a990 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1a9a0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1a9b0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1a9c0 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1a9d0 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1a9e0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1a9f0 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1aa00 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1aa10 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1aa20 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1aa30 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1aa40 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1aa50 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1aa60 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1aa70 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1aa80 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1aa90 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1aaa0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1aab0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1aac0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1aad0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1aae0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1aaf0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1ab00 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1ab10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ab20 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1ab30 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1ab40 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1ab50 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1ab60 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1ab70 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1ab80 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1ab90 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1aba0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1abb0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1abc0 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1abd0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1abe0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1abf0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1ac00 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1ac10 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1ac20 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1ac30 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1ac40 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1ac50 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1ac60 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1ac70 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1ac80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1ac90 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1aca0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1acb0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1acc0 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1acd0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1ace0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1acf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1ad00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ad10 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
1ad20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
1ad30 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
1ad40 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ad50 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
1ad60 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
1ad70 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1ad80 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1ad90 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1ada0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1adb0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1adc0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1add0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1ade0 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1adf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1ae00 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1ae10 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1ae20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ae30 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1ae40 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1ae50 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1ae60 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1ae70 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1ae80 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ae90 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1aea0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1aeb0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1aec0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1aed0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1aee0 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1aef0 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1af00 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1af10 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1af20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1af30 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1af40 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1af50 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1af60 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1af70 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1af80 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1af90 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1afa0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1afb0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1afc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1afd0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1afe0 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1aff0 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1b000 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1b010 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1b020 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b030 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1b040 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1b050 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1b060 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1b070 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1b080 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1b090 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1b0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1b0b0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1b0c0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1b0d0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1b0e0 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1b0f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1b100 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1b110 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1b120 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1b130 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1b140 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1b150 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1b160 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1b170 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1b180 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1b190 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1b1a0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1b1b0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1b1c0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1b1d0 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69  used(void);.sqli
1b1e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1b1f0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1b200 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
1b210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b220 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
1b230 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
1b240 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
1b250 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
1b260 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
1b270 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
1b280 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
1b290 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
1b2a0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
1b2b0 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
1b2c0 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
1b2d0 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
1b2e0 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
1b2f0 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
1b300 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
1b310 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
1b320 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
1b330 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
1b340 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
1b350 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
1b360 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
1b370 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
1b380 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
1b390 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
1b3a0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
1b3b0 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
1b3c0 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
1b3d0 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
1b3e0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
1b3f0 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
1b400 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
1b410 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
1b420 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
1b430 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
1b440 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
1b450 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
1b460 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1b470 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1b480 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
1b490 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1b4a0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1b4b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b4c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1b4d0 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
1b4e0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
1b4f0 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
1b500 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
1b510 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
1b520 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
1b530 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
1b540 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
1b550 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
1b560 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
1b570 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1b580 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1b590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b5a0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1b5b0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1b5c0 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
1b5d0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
1b5e0 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
1b5f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
1b600 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1b610 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1b620 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
1b630 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1b640 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
1b650 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1b660 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
1b670 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
1b680 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
1b690 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
1b6a0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
1b6b0 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
1b6c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b6d0 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
1b6e0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
1b6f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
1b700 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
1b710 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
1b720 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
1b730 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
1b740 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
1b750 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
1b760 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
1b770 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
1b780 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b790 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1b7a0 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
1b7b0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
1b7c0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
1b7d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b7e0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
1b7f0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
1b800 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
1b810 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
1b820 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
1b830 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
1b840 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
1b850 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b860 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
1b870 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
1b880 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
1b890 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
1b8a0 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
1b8b0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
1b8c0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
1b8d0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
1b8e0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1b8f0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
1b900 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
1b910 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
1b920 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
1b930 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
1b940 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
1b950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1b960 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1b970 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1b980 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
1b990 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1b9a0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1b9b0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
1b9c0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
1b9d0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
1b9e0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
1b9f0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
1ba00 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
1ba10 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
1ba20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ba30 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
1ba40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
1ba50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1ba60 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1ba70 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
1ba80 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1ba90 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1baa0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1bab0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
1bac0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
1bad0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
1bae0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1baf0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
1bb00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1bb10 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
1bb20 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
1bb30 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1bb40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bb50 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
1bb60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1bb70 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
1bb80 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1bb90 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
1bba0 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
1bbb0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
1bbc0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1bbd0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
1bbe0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
1bbf0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
1bc00 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
1bc10 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1bc20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
1bc30 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1bc40 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
1bc50 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
1bc60 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
1bc70 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
1bc80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1bc90 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
1bca0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
1bcb0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1bcc0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1bcd0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1bce0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
1bcf0 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
1bd00 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
1bd10 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
1bd20 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
1bd30 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
1bd40 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
1bd50 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
1bd60 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
1bd70 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
1bd80 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
1bd90 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
1bda0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
1bdb0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
1bdc0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
1bdd0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
1bde0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
1bdf0 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
1be00 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
1be10 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
1be20 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
1be30 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1be40 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
1be50 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
1be60 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
1be70 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
1be80 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
1be90 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
1bea0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
1beb0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
1bec0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
1bed0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
1bee0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
1bef0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1bf00 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
1bf10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bf20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
1bf30 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
1bf40 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
1bf50 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
1bf60 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
1bf70 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
1bf80 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
1bf90 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
1bfa0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
1bfb0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
1bfc0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
1bfd0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
1bfe0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
1bff0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
1c000 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
1c010 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
1c020 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
1c030 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
1c040 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
1c050 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
1c060 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1c070 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
1c080 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
1c090 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
1c0a0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
1c0b0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
1c0c0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
1c0d0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
1c0e0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
1c0f0 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
1c100 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
1c110 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
1c120 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
1c130 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
1c140 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
1c150 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
1c160 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
1c170 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
1c180 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
1c190 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
1c1a0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
1c1b0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
1c1c0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
1c1d0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
1c1e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
1c1f0 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
1c200 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
1c210 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
1c220 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
1c230 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
1c240 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
1c250 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
1c260 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
1c270 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
1c280 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
1c290 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
1c2a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
1c2b0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
1c2c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
1c2d0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
1c2e0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
1c2f0 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
1c300 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
1c310 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
1c320 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
1c330 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
1c340 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
1c350 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
1c360 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
1c370 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
1c380 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
1c390 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
1c3a0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
1c3b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c3c0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c3d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1c3e0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
1c3f0 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
1c400 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
1c410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
1c420 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
1c430 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c440 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
1c450 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
1c460 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
1c470 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
1c480 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c490 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
1c4a0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
1c4b0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
1c4c0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
1c4d0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
1c4e0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
1c4f0 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
1c500 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
1c510 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
1c520 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
1c530 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
1c540 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
1c550 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1c560 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
1c570 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
1c580 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1c590 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
1c5a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c5b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1c5c0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
1c5d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1c5e0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
1c5f0 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
1c600 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
1c610 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
1c620 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
1c630 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
1c640 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
1c650 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
1c660 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1c670 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
1c680 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
1c690 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
1c6a0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
1c6b0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
1c6c0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
1c6d0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74  a change..*/.int
1c6e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1c6f0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1c700 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1c710 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1c720 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1c730 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1c740 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1c750 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1c760 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1c770 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1c780 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1c790 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1c7a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1c7b0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1c7c0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1c7d0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1c7e0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1c7f0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1c800 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1c810 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1c820 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1c830 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1c840 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1c850 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1c860 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1c870 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1c880 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1c890 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1c8a0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1c8b0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1c8c0 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1c8d0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1c8e0 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1c8f0 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1c900 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1c910 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1c920 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1c930 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1c940 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1c950 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1c960 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c970 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1c980 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c990 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1c9a0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1c9b0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1c9c0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1c9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c9e0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1c9f0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1ca00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1ca10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1ca20 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1ca30 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1ca40 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1ca50 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1ca60 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1ca70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1ca80 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1ca90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1caa0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1cab0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1cac0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1cad0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1cae0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1caf0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1cb00 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1cb10 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1cb20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1cb30 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1cb40 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1cb50 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1cb60 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1cb70 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1cb80 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1cb90 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1cba0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1cbb0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1cbc0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1cbd0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1cbe0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1cbf0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1cc00 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1cc10 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1cc20 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1cc30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1cc40 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1cc50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1cc60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1cc70 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1cc80 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1cc90 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1cca0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1ccb0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1ccc0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1ccd0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1cce0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1ccf0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1cd00 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1cd10 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1cd20 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1cd30 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1cd40 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1cd50 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1cd60 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1cd70 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1cd80 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1cd90 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
1cda0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cdb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1cdc0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1cdd0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1cde0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1cdf0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1ce00 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1ce10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1ce20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ce30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ce40 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1ce50 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1ce60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ce70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ce80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ce90 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1cea0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1ceb0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cec0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ced0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cee0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1cef0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1cf00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1cf10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cf20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cf30 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1cf40 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1cf50 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1cf60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1cf70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cf80 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1cf90 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1cfa0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1cfb0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cfc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1cfd0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1cfe0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1cff0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1d000 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d010 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d020 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1d030 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1d040 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1d050 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1d070 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1d080 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1d090 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1d0a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d0b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d0c0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1d0d0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1d0e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1d0f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d100 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d110 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1d120 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1d130 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d140 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d150 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d160 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1d170 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1d180 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1d190 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d1a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1d1b0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1d1c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d1d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d1e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d1f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1d200 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1d210 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1d220 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1d230 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d240 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1d250 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1d260 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1d270 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1d280 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1d290 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1d2a0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1d2b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1d2c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d2d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d2e0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1d2f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1d300 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1d310 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d320 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d330 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1d340 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1d350 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d360 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1d370 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d380 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1d390 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1d3a0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1d3b0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1d3c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d3d0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1d3e0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1d3f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1d400 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1d410 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d420 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1d430 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1d440 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1d450 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d470 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1d480 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1d490 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1d4a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d4b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1d4c0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1d4d0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1d4e0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1d4f0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1d500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1d510 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1d520 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1d530 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1d540 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1d560 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1d570 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1d580 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1d590 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1d5a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1d5b0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1d5c0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1d5d0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1d5e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1d5f0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1d600 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1d610 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1d620 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d630 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d640 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1d650 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1d660 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1d670 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1d680 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1d690 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1d6a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1d6b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d6c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1d6d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1d6e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1d6f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1d700 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1d710 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1d720 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d730 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1d740 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1d750 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1d760 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1d770 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1d780 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1d790 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1d7a0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1d7b0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1d7c0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1d7d0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1d7e0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1d7f0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1d800 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1d810 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1d820 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1d830 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1d840 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1d850 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1d860 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1d870 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1d880 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1d890 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1d8a0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1d8b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1d8c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d8d0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1d8e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d8f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1d900 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1d910 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1d920 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1d930 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1d940 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1d950 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1d960 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d970 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1d980 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1d990 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d9a0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1d9b0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1d9c0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1d9d0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1d9e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d9f0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1da00 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1da10 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1da20 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1da30 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1da40 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1da50 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1da60 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1da70 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1da80 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1da90 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1daa0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1dab0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1dac0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1dad0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1dae0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1daf0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1db00 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1db10 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1db20 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1db30 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1db40 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1db50 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1db60 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1db70 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1db80 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1db90 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1dba0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1dbb0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1dbc0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1dbd0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1dbe0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1dbf0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1dc00 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1dc10 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1dc20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1dc30 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1dc40 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1dc50 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1dc60 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1dc70 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1dc80 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1dc90 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1dca0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1dcb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1dcc0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1dcd0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1dce0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1dcf0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1dd00 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1dd10 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1dd20 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  te..*/.void *sql
1dd30 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1dd40 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1dd50 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1dd60 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1dd70 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1dd80 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1dd90 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1dda0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1ddb0 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1ddc0 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1ddd0 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1dde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ddf0 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1de00 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1de10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1de20 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1de30 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1de40 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1de50 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1de60 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1de70 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1de80 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1de90 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1dea0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1deb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1dec0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1ded0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1dee0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1def0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1df00 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1df10 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1df20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1df30 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1df40 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1df50 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1df60 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1df70 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1df80 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1df90 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1dfa0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1dfb0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1dfc0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1dfd0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1dfe0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1dff0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1e000 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1e010 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1e020 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1e030 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1e040 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1e050 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e060 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1e070 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1e080 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e090 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1e0a0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1e0b0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1e0c0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1e0d0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1e0e0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1e0f0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1e100 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1e110 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1e120 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1e130 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1e140 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1e150 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1e160 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1e170 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1e180 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1e190 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1e1a0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1e1b0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1e1c0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1e1d0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1e1e0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1e1f0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1e200 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1e210 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1e220 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1e230 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e240 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e250 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e260 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e270 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e280 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1e290 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1e2a0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1e2b0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1e2c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1e2d0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1e2e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1e2f0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1e300 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1e310 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1e320 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
1e330 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
1e340 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
1e350 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
1e360 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
1e370 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e380 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
1e390 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
1e3a0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
1e3b0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
1e3c0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
1e3d0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
1e3e0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1e3f0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1e400 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
1e410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
1e420 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
1e430 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
1e440 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1e450 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
1e460 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
1e470 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
1e480 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
1e490 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
1e4a0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
1e4b0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
1e4c0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
1e4d0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
1e4e0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
1e4f0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
1e500 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
1e510 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
1e520 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
1e530 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
1e540 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
1e550 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
1e560 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
1e570 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
1e580 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
1e590 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
1e5a0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
1e5b0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
1e5c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1e5d0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
1e5e0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
1e5f0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
1e600 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
1e610 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
1e620 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1e630 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
1e640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
1e650 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
1e660 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
1e670 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
1e680 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
1e690 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
1e6a0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
1e6b0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
1e6c0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
1e6d0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
1e6e0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
1e6f0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1e700 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
1e710 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
1e720 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
1e730 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
1e740 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1e750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e760 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
1e770 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
1e780 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
1e790 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
1e7a0 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
1e7b0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
1e7c0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
1e7d0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
1e7e0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
1e7f0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
1e800 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
1e810 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
1e820 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
1e830 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
1e840 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
1e850 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
1e860 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
1e870 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
1e880 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
1e890 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
1e8a0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
1e8b0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
1e8c0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
1e8d0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
1e8e0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
1e8f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
1e900 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
1e910 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
1e920 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
1e930 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
1e940 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
1e950 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
1e960 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
1e970 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
1e980 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
1e990 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
1e9a0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
1e9b0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1e9c0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
1e9d0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
1e9e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1e9f0 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
1ea00 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1ea10 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
1ea20 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
1ea30 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
1ea40 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
1ea50 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
1ea60 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
1ea70 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ea80 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
1ea90 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
1eaa0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
1eab0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
1eac0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
1ead0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1eae0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1eaf0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1eb00 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
1eb10 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
1eb20 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1eb30 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
1eb40 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
1eb50 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
1eb60 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
1eb70 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
1eb80 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
1eb90 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
1eba0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
1ebb0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
1ebc0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
1ebd0 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
1ebe0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1ebf0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1ec00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ec10 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
1ec20 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
1ec30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1ec40 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1ec50 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
1ec60 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
1ec70 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
1ec80 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
1ec90 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
1eca0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
1ecb0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
1ecc0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
1ecd0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1ece0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
1ecf0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
1ed00 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
1ed10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ed20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1ed30 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
1ed40 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
1ed50 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
1ed60 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
1ed70 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
1ed80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1ed90 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
1eda0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
1edb0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1edc0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
1edd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
1ede0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1edf0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
1ee00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ee10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1ee20 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
1ee30 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
1ee40 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
1ee50 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
1ee60 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
1ee70 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
1ee80 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1ee90 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
1eea0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
1eeb0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
1eec0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
1eed0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1eee0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
1eef0 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
1ef00 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
1ef10 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
1ef20 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
1ef30 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1ef40 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
1ef50 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1ef60 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
1ef70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1ef80 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
1ef90 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
1efa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
1efb0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
1efc0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
1efd0 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
1efe0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1eff0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
1f000 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
1f010 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1f020 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
1f030 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
1f040 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1f050 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
1f060 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1f070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f080 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
1f090 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
1f0a0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
1f0b0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
1f0c0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
1f0d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
1f0e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1f0f0 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
1f100 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
1f110 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1f120 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
1f130 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
1f140 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
1f150 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
1f160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f170 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
1f180 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1f190 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
1f1a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1f1b0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
1f1c0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1f1d0 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
1f1e0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1f1f0 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
1f200 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1f210 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
1f220 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
1f230 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
1f240 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
1f250 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
1f260 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
1f270 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
1f280 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f290 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1f2a0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1f2b0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
1f2c0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
1f2d0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
1f2e0 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
1f2f0 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
1f300 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
1f310 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
1f320 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
1f330 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
1f340 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
1f350 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
1f360 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
1f370 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
1f380 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
1f390 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
1f3a0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
1f3b0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
1f3c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
1f3d0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
1f3e0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
1f3f0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1f400 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
1f410 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
1f420 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
1f430 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
1f440 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
1f450 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
1f460 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
1f470 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1f480 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1f490 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
1f4a0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
1f4b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
1f4c0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
1f4d0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
1f4e0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
1f4f0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1f500 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
1f510 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1f520 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
1f530 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
1f540 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1f550 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f560 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
1f570 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1f580 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1f590 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
1f5a0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
1f5b0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
1f5c0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1f5d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f5e0 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
1f5f0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
1f600 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
1f610 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
1f620 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
1f630 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
1f640 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
1f650 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
1f660 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
1f670 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
1f680 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
1f690 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1f6a0 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
1f6b0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
1f6c0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
1f6d0 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
1f6e0 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
1f6f0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
1f700 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
1f710 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
1f720 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
1f730 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
1f740 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
1f750 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1f760 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1f770 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
1f780 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
1f790 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
1f7a0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
1f7b0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
1f7c0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
1f7d0 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
1f7e0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1f7f0 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
1f800 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
1f810 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
1f820 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
1f830 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
1f840 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
1f850 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1f860 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
1f870 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
1f880 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
1f890 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
1f8a0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
1f8b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
1f8c0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
1f8d0 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
1f8e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f8f0 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
1f900 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
1f910 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
1f920 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
1f930 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
1f940 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
1f950 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1f960 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
1f970 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
1f980 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
1f990 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
1f9a0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
1f9b0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
1f9c0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
1f9d0 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
1f9e0 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
1f9f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fa00 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
1fa10 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
1fa20 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
1fa30 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
1fa40 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
1fa50 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
1fa60 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
1fa70 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
1fa80 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
1fa90 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
1faa0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1fab0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
1fac0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
1fad0 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
1fae0 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
1faf0 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
1fb00 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
1fb10 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
1fb20 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
1fb30 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
1fb40 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1fb50 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  ree query parame
1fb60 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
1fb70 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
1fb80 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
1fb90 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
1fba0 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
1fbb0 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
1fbc0 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
1fbd0 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
1fbe0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1fbf0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1fc00 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
1fc10 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
1fc20 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1fc30 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
1fc40 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
1fc50 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
1fc60 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1fc70 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
1fc80 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
1fc90 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
1fca0 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
1fcb0 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
1fcc0 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
1fcd0 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
1fce0 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
1fcf0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
1fd00 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
1fd10 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
1fd20 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
1fd30 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
1fd40 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
1fd50 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
1fd60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1fd70 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1fd80 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
1fd90 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
1fda0 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
1fdb0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1fdc0 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
1fdd0 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
1fde0 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
1fdf0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
1fe00 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
1fe10 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
1fe20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
1fe30 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
1fe40 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
1fe50 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
1fe60 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1fe70 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
1fe80 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
1fe90 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
1fea0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
1feb0 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
1fec0 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
1fed0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1fee0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fef0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1ff00 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1ff10 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1ff20 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1ff30 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1ff40 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1ff50 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1ff60 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1ff70 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1ff80 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1ff90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1ffa0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1ffb0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
1ffc0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
1ffd0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1ffe0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
1fff0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20000 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
20010 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
20020 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
20030 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
20040 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
20050 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
20060 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
20070 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
20080 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
20090 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
200a0 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
200b0 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
200c0 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
200d0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
200e0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
200f0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
20100 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
20110 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
20120 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
20130 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
20140 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
20150 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
20160 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
20170 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
20180 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
20190 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
201a0 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
201b0 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
201c0 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
201d0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
201e0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
201f0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
20200 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
20210 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
20220 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
20230 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
20240 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
20250 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
20260 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
20270 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
20280 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
20290 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
202a0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
202b0 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
202c0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
202d0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
202e0 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
202f0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
20300 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
20310 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
20320 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
20330 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
20340 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
20350 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
20360 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
20370 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
20380 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
20390 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
203a0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
203b0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
203c0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
203d0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
203e0 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
203f0 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
20400 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
20410 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
20420 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
20430 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
20440 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
20450 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
20460 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
20470 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
20480 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
20490 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
204a0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
204b0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
204c0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
204d0 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
204e0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
204f0 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
20500 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
20510 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
20520 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
20530 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
20540 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
20550 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
20560 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
20570 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
20580 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
20590 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
205a0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
205b0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
205c0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
205d0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
205e0 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
205f0 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
20600 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
20610 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
20620 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
20630 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
20640 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
20650 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
20660 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
20670 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
20680 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
20690 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
206a0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
206b0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
206c0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
206d0 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
206e0 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
206f0 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
20700 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
20710 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
20720 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
20730 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
20740 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
20750 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
20760 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
20770 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
20780 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
20790 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
207a0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
207b0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
207c0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
207d0 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
207e0 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
207f0 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
20800 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
20810 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
20820 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
20830 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
20840 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
20850 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
20860 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
20870 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
20880 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
20890 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
208a0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
208b0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
208c0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
208d0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
208e0 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
208f0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
20900 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
20910 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
20920 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
20930 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
20940 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
20950 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
20960 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
20970 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
20980 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
20990 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
209a0 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
209b0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
209c0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
209d0 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
209e0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
209f0 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
20a00 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
20a10 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
20a20 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
20a30 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
20a40 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
20a50 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
20a60 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
20a70 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
20a80 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
20a90 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
20aa0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
20ab0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20ac0 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
20ad0 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
20ae0 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
20af0 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
20b00 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
20b10 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
20b20 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
20b30 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
20b40 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
20b50 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
20b60 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
20b70 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
20b80 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
20b90 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
20ba0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
20bb0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20bc0 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
20bd0 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
20be0 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
20bf0 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
20c00 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
20c10 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
20c20 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
20c30 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
20c40 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
20c50 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
20c60 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
20c70 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
20c80 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
20c90 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
20ca0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
20cb0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
20cc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
20cd0 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
20ce0 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
20cf0 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
20d00 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
20d10 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
20d20 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
20d30 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
20d40 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
20d50 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
20d60 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
20d70 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
20d80 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20d90 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
20da0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
20db0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
20dc0 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
20dd0 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
20de0 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
20df0 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
20e00 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
20e10 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
20e20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
20e30 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
20e40 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
20e50 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
20e60 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
20e70 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
20e80 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
20e90 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
20ea0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69  _directory].*/.i
20eb0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
20ec0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
20ed0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
20ee0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
20ef0 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
20f00 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
20f10 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
20f20 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
20f30 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
20f40 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
20f50 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
20f60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
20f70 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
20f80 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
20f90 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
20fa0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
20fb0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
20fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20fd0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
20fe0 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
20ff0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21000 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
21010 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
21020 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
21030 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
21040 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
21050 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
21060 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
21070 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
21080 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
21090 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
210a0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
210b0 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
210c0 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
210d0 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
210e0 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
210f0 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
21100 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
21110 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
21120 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
21130 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
21140 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
21150 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
21160 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
21170 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
21180 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
21190 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
211a0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
211b0 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
211c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
211d0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
211e0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
211f0 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
21200 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
21210 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
21220 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
21230 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
21240 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
21250 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21260 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
21270 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
21280 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
21290 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
212a0 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
212b0 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
212c0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
212d0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
212e0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
212f0 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
21300 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
21310 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
21320 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
21330 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
21340 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
21350 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
21360 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
21370 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
21380 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
21390 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
213a0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
213b0 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
213c0 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
213d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
213e0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
213f0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
21400 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
21410 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
21420 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
21430 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21440 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
21450 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
21460 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
21470 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
21480 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
21490 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
214a0 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
214b0 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
214c0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
214d0 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
214e0 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
214f0 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
21500 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
21510 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
21520 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
21530 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
21540 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21550 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
21560 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
21570 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
21580 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
21590 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
215a0 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
215b0 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
215c0 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
215d0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
215e0 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
215f0 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
21600 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
21610 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
21620 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
21630 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
21640 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
21650 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
21660 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
21670 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
21680 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21690 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
216a0 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
216b0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
216c0 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
216d0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
216e0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
216f0 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
21700 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
21710 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
21720 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
21730 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
21740 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
21750 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
21760 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
21770 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
21780 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
21790 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
217a0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
217b0 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
217c0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
217d0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
217e0 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
217f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
21800 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
21810 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
21820 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
21830 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
21840 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
21850 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
21860 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
21870 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
21880 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
21890 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
218a0 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e  esirable..*/.con
218b0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
218c0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
218d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
218e0 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
218f0 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73   *zParam);.int s
21900 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21910 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
21920 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
21930 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
21940 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33  efault);.sqlite3
21950 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  _int64 sqlite3_u
21960 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63  ri_int64(const c
21970 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  har*, const char
21980 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
21990 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
219a0 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73  REF: Error Codes
219b0 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a   And Messages.**
219c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
219d0 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72  _errcode() inter
219e0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
219f0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
21a00 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
21a10 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21a20 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74  de] for the most
21a30 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73   recent failed s
21a40 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
21a50 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  l.** associated 
21a60 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
21a70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66   connection]. If
21a80 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c   a prior API cal
21a90 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20  l failed.** but 
21aa0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
21ab0 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64  API call succeed
21ac0 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ed, the return v
21ad0 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  alue from.** sql
21ae0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
21af0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54  s undefined.  ^T
21b00 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
21b10 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a  ded_errcode().**
21b20 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
21b30 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68  e same except th
21b40 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  at it always ret
21b50 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78  urns the .** [ex
21b60 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21b70 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78  de] even when ex
21b80 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
21b90 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  des are.** disab
21ba0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
21bb0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
21bc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
21bd0 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
21be0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
21bf0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
21c00 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
21c10 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
21c20 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
21c30 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d  ectively..** ^(M
21c40 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21c50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
21c60 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
21c70 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a  d internally..**
21c80 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
21c90 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
21ca0 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72  o worry about fr
21cb0 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  eeing the result
21cc0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
21cd0 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d  e error string m
21ce0 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74  ight be overwrit
21cf0 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ten or deallocat
21d00 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75  ed by.** subsequ
21d10 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68  ent calls to oth
21d20 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
21d30 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e  ace functions.)^
21d40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21d50 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74  te3_errstr() int
21d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21d70 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  he English-langu
21d80 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74  age text.** that
21d90 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b   describes the [
21da0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73  result code], as
21db0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d   UTF-8..** ^(Mem
21dc0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
21dd0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
21de0 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
21df0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e  internally.** an
21e00 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72  d must not be fr
21e10 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  eed by the appli
21e20 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20  cation)^..**.** 
21e30 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
21e40 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
21e50 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
21e60 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
21e70 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
21e80 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
21e90 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
21ea0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
21eb0 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
21ec0 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
21ed0 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
21ee0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
21ef0 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
21f00 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
21f10 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
21f20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
21f30 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
21f40 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
21f50 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
21f60 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
21f70 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
21f80 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
21f90 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
21fa0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
21fb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
21fc0 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
21fd0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
21fe0 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
21ff0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
22000 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
22010 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
22020 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
22030 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
22040 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
22050 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
22060 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
22070 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
22080 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
22090 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
220a0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
220b0 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
220c0 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
220d0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
220e0 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
220f0 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
22100 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
22110 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
22120 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
22130 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
22140 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
22150 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
22160 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
22170 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
22180 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
22190 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
221a0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
221b0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
221c0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
221d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
221e0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
221f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
22200 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
22210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22220 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
22230 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
22240 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
22250 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
22260 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
22270 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
22280 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
22290 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
222a0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
222b0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
222c0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
222d0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
222e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
222f0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
22300 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
22310 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
22320 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
22330 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
22340 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
22350 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
22360 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
22370 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
22380 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
22390 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
223a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
223b0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
223c0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
223d0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
223e0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
223f0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
22400 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
22410 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
22420 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
22430 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
22440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
22450 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
22460 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
22470 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
22480 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
22490 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
224a0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
224b0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
224c0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
224d0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
224e0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
224f0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
22500 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
22510 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
22520 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
22530 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
22540 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
22550 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22560 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
22570 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
22580 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
22590 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
225a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
225b0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
225c0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
225d0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
225e0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
225f0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
22600 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
22610 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
22620 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
22630 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
22640 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
22650 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22660 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
22670 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
22680 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
22690 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
226a0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
226b0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
226c0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
226d0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
226e0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
226f0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
22700 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22710 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
22720 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
22730 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
22740 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
22750 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
22760 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
22770 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
22780 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
22790 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
227a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
227b0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
227c0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
227d0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
227e0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
227f0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
22800 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
22810 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
22820 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
22830 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
22840 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
22850 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
22860 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
22870 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
22880 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
22890 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
228a0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
228b0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
228c0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
228d0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
228e0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
228f0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
22900 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22910 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
22920 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
22930 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
22940 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22950 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
22960 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
22970 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
22980 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
22990 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
229a0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
229b0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
229c0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
229d0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
229e0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
229f0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
22a00 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
22a10 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
22a20 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
22a30 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
22a40 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
22a50 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
22a60 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
22a70 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
22a80 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
22a90 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
22aa0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
22ab0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
22ac0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
22ad0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
22ae0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
22af0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
22b00 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
22b10 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
22b20 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
22b30 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
22b40 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
22b50 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
22b60 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
22b70 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
22b80 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
22b90 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
22ba0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
22bb0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
22bc0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
22bd0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
22be0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
22bf0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
22c00 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
22c10 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
22c20 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
22c30 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
22c40 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
22c50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
22c60 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
22c70 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
22c80 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
22c90 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
22ca0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
22cb0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
22cc0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
22cd0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
22ce0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
22cf0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
22d00 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
22d10 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
22d20 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
22d30 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
22d40 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
22d50 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
22d60 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
22d70 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
22d80 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
22d90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
22da0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
22db0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
22dc0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
22dd0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
22de0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
22df0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
22e00 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
22e10 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
22e20 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
22e30 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
22e40 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
22e50 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
22e60 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
22e70 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
22e80 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
22e90 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
22ea0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
22eb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
22ec0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
22ed0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
22ee0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
22ef0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
22f00 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
22f10 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
22f20 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
22f30 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22f40 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
22f50 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
22f60 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
22f70 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
22f80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
22f90 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
22fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
22fb0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
22fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22fd0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
22fe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
22ff0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
23000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
23010 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
23020 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
23030 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
23040 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23050 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
23060 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
23070 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
23080 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
23090 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
230a0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
230b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
230c0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
230d0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
230e0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
230f0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
23100 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23110 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
23120 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23130 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
23140 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23150 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
23160 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
23170 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
23180 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23190 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
231a0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
231b0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
231c0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
231d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
231e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
231f0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
23200 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
23210 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
23220 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23230 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
23240 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
23250 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
23260 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
23270 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
23280 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
23290 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
232a0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
232b0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
232c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
232d0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
232e0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
232f0 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
23300 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
23310 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
23320 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
23330 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
23340 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23350 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
23360 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23370 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
23380 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23390 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
233a0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
233b0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
233c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
233d0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
233e0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
233f0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
23400 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23410 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23420 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
23430 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
23440 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
23450 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
23460 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
23470 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
23480 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
23490 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
234a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
234b0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
234c0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
234d0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
234e0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
234f0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
23500 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23510 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
23520 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
23530 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
23540 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
23550 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
23560 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
23570 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
23580 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
23590 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
235a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
235b0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
235c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
235d0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
235e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
235f0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
23600 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
23610 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
23620 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
23630 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
23640 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
23650 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
23660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
23670 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
23680 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
23690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
236a0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
236b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
236c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
236d0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
236e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
236f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23700 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
23710 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
23720 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
23730 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
23740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23750 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
23760 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
23770 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
23780 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
23790 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
237a0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
237b0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
237c0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
237d0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
237e0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
237f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
23800 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
23810 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
23820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
23830 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
23840 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
23850 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
23860 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
23870 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
23880 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
23890 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
238a0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
238b0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
238c0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
238d0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
238e0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
238f0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
23900 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
23910 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
23920 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
23930 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23940 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
23950 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
23960 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
23970 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
23980 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
23990 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
239a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
239b0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
239c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
239d0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
239e0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
239f0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
23a00 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
23a10 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
23a20 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
23a30 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
23a40 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
23a50 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
23a60 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
23a70 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23a80 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
23a90 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
23aa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
23ab0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
23ac0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
23ad0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
23ae0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
23af0 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
23b00 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
23b10 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
23b20 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
23b30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
23b40 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
23b50 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
23b60 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
23b70 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
23b80 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
23b90 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
23ba0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
23bb0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
23bc0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
23bd0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
23be0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
23bf0 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
23c00 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
23c10 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
23c20 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
23c30 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
23c40 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
23c50 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
23c60 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
23c70 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
23c80 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
23c90 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
23ca0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
23cb0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
23cc0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
23cd0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
23ce0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
23cf0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
23d00 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
23d10 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
23d20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
23d30 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
23d40 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
23d50 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
23d60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
23d70 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
23d80 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
23d90 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
23da0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
23db0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
23dc0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
23dd0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
23de0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
23df0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
23e00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
23e10 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
23e20 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
23e30 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
23e40 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
23e50 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
23e60 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
23e70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
23e80 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
23e90 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
23ea0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
23eb0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
23ec0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
23ed0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23ee0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
23ef0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
23f00 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
23f10 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
23f20 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
23f30 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
23f40 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
23f50 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
23f60 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
23f70 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
23f80 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
23f90 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
23fa0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
23fb0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
23fc0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
23fd0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
23fe0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
23ff0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
24000 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
24010 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
24020 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
24030 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
24040 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
24050 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
24060 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
24070 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
24080 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
24090 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
240a0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
240b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
240c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
240d0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
240e0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
240f0 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
24100 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
24110 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
24120 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
24130 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
24140 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
24150 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
24160 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
24170 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
24180 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
24190 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
241a0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
241b0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
241c0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
241d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
241e0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
241f0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
24200 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
24210 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
24220 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
24230 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
24240 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
24250 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
24260 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
24270 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
24280 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
24290 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
242a0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
242b0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
242c0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
242d0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
242e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
242f0 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
24300 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
24310 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
24320 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
24330 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
24340 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
24350 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
24360 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
24370 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
24380 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
24390 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
243a0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
243b0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
243c0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
243d0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
243e0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
243f0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
24400 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
24410 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
24420 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
24430 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
24440 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
24450 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
24460 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
24470 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
24480 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
24490 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
244a0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
244b0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
244c0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
244d0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
244e0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
244f0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
24500 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
24510 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
24520 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
24530 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
24540 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
24550 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
24560 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
24570 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
24580 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
24590 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
245a0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
245b0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
245c0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
245d0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
245e0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
245f0 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
24600 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
24610 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
24620 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
24630 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
24640 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
24650 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
24660 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
24670 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
24680 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
24690 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
246a0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
246b0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
246c0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
246d0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
246e0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
246f0 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
24700 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
24710 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
24720 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
24730 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
24740 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
24750 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
24760 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
24770 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
24780 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
24790 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
247a0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
247b0 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
247c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
247d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
247e0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
247f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
24800 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
24810 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24820 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
24830 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
24840 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
24850 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
24860 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24870 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
24880 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
24890 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
248a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
248b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
248c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
248d0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
248e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
248f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
24900 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
24910 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
24920 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
24930 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
24940 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
24950 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
24960 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
24970 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
24980 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
24990 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
249a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
249b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
249c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
249d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
249e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
249f0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
24a00 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
24a10 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
24a20 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
24a30 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
24a40 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
24a50 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
24a60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
24a70 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
24a80 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
24a90 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
24aa0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
24ab0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
24ac0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
24ad0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
24ae0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
24af0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
24b00 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
24b10 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
24b20 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
24b30 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
24b40 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
24b50 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
24b60 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
24b70 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
24b80 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
24b90 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
24ba0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
24bb0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
24bc0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
24bd0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
24be0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
24bf0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
24c00 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
24c10 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
24c20 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
24c30 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
24c40 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24c50 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24c60 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24c70 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24c80 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24c90 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24ca0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
24cb0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24cc0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24cd0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24ce0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
24cf0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
24d00 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
24d10 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
24d20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
24d30 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
24d40 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
24d50 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
24d60 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
24d70 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
24d80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24d90 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
24da0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
24db0 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
24dc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24dd0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
24de0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
24df0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
24e00 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
24e10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24e20 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24e30 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
24e40 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
24e50 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20  ment Writes The 
24e60 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e  Database.**.** ^
24e70 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
24e80 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74  _readonly(X) int
24e90 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24ea0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
24eb0 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66  f.** and only if
24ec0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
24ed0 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65  tatement] X make
24ee0 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e  s no direct chan
24ef0 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f  ges to.** the co
24f00 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24f10 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  abase file..**.*
24f20 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70  * Note that [app
24f30 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
24f50 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  or.** [virtual t
24f60 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61  ables] might cha
24f70 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
24f80 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61   indirectly as a
24f90 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a   side effect.  .
24fa0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
24fb0 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  , if an applicat
24fc0 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75  ion defines a fu
24fd0 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20  nction "eval()" 
24fe0 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b  that .** calls [
24ff0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
25000 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77   then the follow
25010 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
25020 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67  t would.** chang
25030 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
25040 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65  ile through side
25050 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20  -effects:.**.** 
25060 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
25070 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65  >.**    SELECT e
25080 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d  val('DELETE FROM
25090 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a   t1') FROM t2;.*
250a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
250b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20  uote>.**.** But 
250c0 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c  because the [SEL
250d0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64  ECT] statement d
250e0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
250f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25100 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71  .** directly, sq
25110 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
25120 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c  nly() would stil
25130 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e  l return true.)^
25140 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74  .**.** ^Transact
25150 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74  ion control stat
25160 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b  ements such as [
25170 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d  BEGIN], [COMMIT]
25180 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a  , [ROLLBACK],.**
25190 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e   [SAVEPOINT], an
251a0 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73  d [RELEASE] caus
251b0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
251c0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
251d0 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e  urn true,.** sin
251e0 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ce the statement
251f0 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20  s themselves do 
25200 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64  not actually mod
25210 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
25220 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74   but.** rather t
25230 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20  hey control the 
25240 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f  timing of when o
25250 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20  ther statements 
25260 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64  modify the .** d
25270 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b  atabase.  ^The [
25280 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54  ATTACH] and [DET
25290 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ACH] statements 
252a0 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71  also cause.** sq
252b0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
252c0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
252d0 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c  true since, whil
252e0 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e  e those statemen
252f0 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ts.** change the
25300 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
25310 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  f a database con
25320 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f  nection, they do
25330 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68   not make .** ch
25340 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e  anges to the con
25350 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
25360 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69  base files on di
25370 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  sk..*/.int sqlit
25380 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25390 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
253a0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
253b0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
253c0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
253d0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
253e0 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  en Reset.**.** ^
253f0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
25400 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61  _busy(S) interfa
25410 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
25420 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68  (non-zero) if th
25430 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
25440 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20  tatement] S has 
25450 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20  been stepped at 
25460 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67  least once using
25470 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74   .** [sqlite3_st
25480 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e  ep(S)] but has n
25490 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  ot run to comple
254a0 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20  tion and/or has 
254b0 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73  not .** been res
254c0 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  et using [sqlite
254d0 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54  3_reset(S)].  ^T
254e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
254f0 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72  busy(S).** inter
25500 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c  face returns fal
25510 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c  se if S is a NUL
25520 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53  L pointer.  If S
25530 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55   is not a .** NU
25540 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69  LL pointer and i
25550 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20  s not a pointer 
25560 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70  to a valid [prep
25570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
25580 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20  ** object, then 
25590 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
255a0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
255b0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
255c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  le..**.** This i
255d0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
255e0 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74  used in combinat
255f0 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  ion [sqlite3_nex
25600 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20  t_stmt()].** to 
25610 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61  locate all prepa
25620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61  red statements a
25630 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
25640 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f   database .** co
25650 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72  nnection that ar
25660 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69  e in need of bei
25670 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20  ng reset.  This 
25680 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20  can be used,.** 
25690 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20  for example, in 
256a0 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69  diagnostic routi
256b0 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f  nes to search fo
256c0 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73  r prepared .** s
256d0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61  tatements that a
256e0 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61  re holding a tra
256f0 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a  nsaction open..*
25700 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
25710 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
25720 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
25730 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
25740 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
25750 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
25760 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
25770 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
25780 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
25790 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
257a0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
257b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
257c0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
257d0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
257e0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
257f0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
25800 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
25810 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
25820 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
25830 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
25840 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
25850 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
25860 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
25870 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
25880 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
25890 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
258a0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
258b0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
258c0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
258d0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
258e0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
258f0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
25900 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
25910 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
25920 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
25930 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
25940 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
25950 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
25960 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
25970 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25980 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
25990 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
259a0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
259b0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
259c0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
259d0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
259e0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
259f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
25a00 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
25a10 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
25a20 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
25a30 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
25a40 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
25a50 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
25a60 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
25a70 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
25a80 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25a90 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
25aa0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
25ab0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
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 2e 20 20 49 66 20  lue object.  If 
25ae0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
25af0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
25b00 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
25b10 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
25b20 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
25b30 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
25b40 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
25b50 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
25b60 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
25b70 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
25b80 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
25b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
25ba0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
25bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
25bc0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
25bd0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
25be0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
25bf0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
25c00 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
25c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25c20 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
25c30 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
25c40 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
25c50 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
25c60 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
25c70 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
25c80 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
25c90 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
25ca0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
25cb0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
25cc0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
25cd0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
25ce0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25cf0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
25d00 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
25d10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25d20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25d30 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
25d40 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
25d50 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
25d60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
25d70 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25d80 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25d90 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
25da0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
25db0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
25dc0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
25dd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25de0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
25df0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
25e00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25e10 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
25e20 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
25e30 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
25e40 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
25e50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
25e60 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
25e70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25e80 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
25e90 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
25ea0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
25eb0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
25ec0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
25ed0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
25ee0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
25ef0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
25f00 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
25f10 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
25f20 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
25f30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
25f40 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
25f50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
25f60 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
25f70 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
25f80 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
25f90 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
25fa0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
25fb0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
25fc0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
25fd0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
25fe0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25ff0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
26000 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
26010 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26020 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26030 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
26040 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
26050 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
26060 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
26070 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
26080 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
26090 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
260a0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
260b0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
260c0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
260d0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
260e0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
260f0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
26100 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
26110 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
26120 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
26130 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
26140 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
26150 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
26160 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
26170 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
26180 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
26190 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
261a0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
261b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
261c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
261d0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
261e0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
261f0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
26200 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
26210 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
26220 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
26230 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
26240 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
26250 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
26260 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
26270 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
26280 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
26290 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
262a0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
262b0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
262c0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
262d0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
262e0 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
262f0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
26300 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
26310 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
26320 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
26330 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
26340 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
26350 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
26360 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
26370 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
26380 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
26390 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
263a0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
263b0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
263c0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
263d0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
263e0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
263f0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
26400 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26410 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
26420 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
26430 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
26440 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
26450 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26460 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
26470 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
26480 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
26490 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
264a0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
264b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
264c0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
264d0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
264e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
264f0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
26500 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
26510 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
26520 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
26530 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
26540 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
26550 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
26560 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
26570 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
26580 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
26590 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
265a0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
265b0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
265c0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
265d0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
265e0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
265f0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
26600 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
26610 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
26620 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26630 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26640 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
26650 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
26660 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
26670 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
26680 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
26690 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
266a0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
266b0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
266c0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
266d0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
266e0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
266f0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
26700 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
26710 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
26720 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
26730 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
26740 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
26750 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
26760 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
26770 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
26780 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
26790 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
267a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
267b0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
267c0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
267d0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
267e0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
267f0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
26800 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
26810 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
26820 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
26830 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
26850 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
26860 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
26870 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
26880 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
26890 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
268a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
268b0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
268c0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
268d0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
268e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
268f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
26900 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
26910 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
26920 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
26930 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
26940 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
26950 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
26960 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
26970 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
26980 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
26990 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
269a0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
269b0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
269c0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
269d0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
269e0 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
269f0 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
26a00 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
26a10 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
26a20 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
26a30 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
26a40 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
26a50 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
26a60 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
26a70 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
26a80 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
26a90 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
26aa0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
26ab0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
26ac0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
26ad0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
26ae0 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
26af0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
26b00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26b10 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
26b20 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
26b30 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
26b40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
26b50 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
26b60 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
26b70 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
26b80 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
26b90 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
26ba0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
26bb0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
26bc0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
26bd0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
26be0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
26bf0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
26c00 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
26c10 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
26c20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
26c30 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
26c40 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
26c50 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
26c60 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
26c70 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
26c80 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
26c90 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
26ca0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
26cb0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
26cc0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
26cd0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
26ce0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
26cf0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
26d00 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
26d10 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
26d20 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
26d30 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
26d40 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
26d50 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
26d60 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
26d70 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
26d80 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
26d90 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
26da0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26db0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
26dc0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
26dd0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
26de0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
26df0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
26e00 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
26e10 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
26e20 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
26e30 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
26e40 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
26e50 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
26e60 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
26e70 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
26e80 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
26e90 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
26ea0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
26eb0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
26ec0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
26ed0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
26ee0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
26ef0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
26f00 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
26f10 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
26f20 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
26f30 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
26f40 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
26f50 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
26f60 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
26f70 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
26f80 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
26f90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
26fa0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
26fb0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
26fc0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
26fd0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
26fe0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
26ff0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
27000 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
27010 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27020 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
27030 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
27040 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
27050 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
27060 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
27070 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
27080 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
27090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
270a0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
270b0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
270c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
270d0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
270e0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
270f0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
27100 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
27110 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
27120 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
27130 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
27140 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
27150 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
27160 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
27170 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
27180 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
27190 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
271a0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
271b0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
271c0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
271d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
271e0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
271f0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
27200 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
27210 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
27220 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
27230 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
27240 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
27250 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
27260 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
27270 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27280 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27290 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
272a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
272b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
272c0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
272d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
272e0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
272f0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27300 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
27310 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
27320 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
27330 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
27340 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
27350 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
27360 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
27370 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
27380 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
27390 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
273a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
273b0 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
273c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
273d0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
273e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
273f0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
27400 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
27410 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
27420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27430 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
27440 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
27450 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
27460 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
27470 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27480 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
27490 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
274a0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
274b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
274c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
274d0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
274e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
274f0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
27500 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
27510 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
27520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
27530 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
27540 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
27550 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
27560 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
27570 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
27580 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
27590 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
275a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
275b0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
275c0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
275d0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
275e0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
275f0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
27600 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
27610 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
27620 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
27630 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27640 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
27650 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
27660 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
27670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
27680 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
27690 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
276a0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
276b0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
276c0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
276d0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
276e0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
276f0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
27700 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
27710 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
27720 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
27730 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
27740 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
27750 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
27760 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
27770 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27790 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
277a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
277b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
277c0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
277d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
277e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
277f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
27800 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
27810 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
27820 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
27830 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
27840 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
27850 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27860 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27870 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
27880 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
27890 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
278a0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
278b0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
278c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
278d0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
278e0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
278f0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
27900 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
27910 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
27920 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
27930 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
27940 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
27950 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
27960 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
27970 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
27980 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
27990 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
279a0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
279b0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
279c0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
279d0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
279e0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
279f0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
27a00 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
27a10 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
27a20 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
27a30 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
27a40 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
27a50 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
27a60 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
27a70 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
27a80 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
27a90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27aa0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
27ab0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
27ac0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
27ad0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
27ae0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
27af0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
27b00 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27b10 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
27b20 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
27b30 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
27b40 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
27b50 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
27b60 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
27b70 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
27b80 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
27b90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27ba0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
27bb0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
27bc0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
27bd0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
27be0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
27bf0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
27c00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
27c10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27c20 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
27c30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
27c40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27c50 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
27c60 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
27c70 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
27c80 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
27c90 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
27ca0 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
27cb0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
27cc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
27cd0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
27ce0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
27cf0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
27d00 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
27d10 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
27d20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
27d30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
27d40 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
27d50 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
27d60 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
27d70 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
27d80 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
27d90 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
27da0 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
27db0 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
27dc0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
27dd0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
27de0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
27df0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
27e00 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
27e10 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
27e20 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
27e30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
27e40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
27e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27e60 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27e70 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
27e80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27e90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
27ea0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
27eb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
27ec0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
27ed0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
27ee0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
27ef0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
27f00 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
27f10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
27f20 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
27f30 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
27f40 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
27f50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
27f60 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
27f70 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
27f80 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
27f90 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
27fa0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
27fb0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
27fc0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
27fd0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
27fe0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
27ff0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
28000 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
28010 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
28020 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
28030 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
28040 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
28050 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
28060 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28070 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
28080 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
28090 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
280a0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
280b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
280c0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
280d0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
280e0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
280f0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
28100 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
28110 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
28120 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
28130 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
28140 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
28150 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
28160 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
28180 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
28190 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
281a0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
281b0 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
281c0 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
281d0 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
281e0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
281f0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
28200 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
28210 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
28220 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
28230 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28240 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28250 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
28260 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
28270 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
28280 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
28290 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
282a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
282b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
282c0 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
282d0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
282e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
282f0 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
28300 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
28310 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
28320 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
28330 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28340 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
28350 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
28360 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
28370 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
28380 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
28390 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
283a0 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
283b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
283c0 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
283d0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
283e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
283f0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
28400 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
28410 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
28420 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
28430 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
28440 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
28450 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
28460 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
28470 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
28480 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
28490 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
284a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
284b0 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
284c0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
284d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
284e0 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
284f0 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
28500 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
28510 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
28520 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
28530 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
28540 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
28550 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
28560 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
28570 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
28580 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
28590 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
285a0 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
285b0 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
285c0 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
285d0 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
285e0 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
285f0 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
28600 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
28610 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
28620 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
28630 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
28640 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
28650 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
28660 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
28680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28690 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
286a0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
286b0 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
286c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
286d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
286e0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
286f0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
28700 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
28710 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
28720 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
28730 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
28740 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
28750 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
28760 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
28770 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
28780 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
28790 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
287a0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
287b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
287c0 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
287d0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
287e0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
287f0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
28800 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
28810 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
28820 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
28830 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
28840 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
28850 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
28860 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
28870 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
28880 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
28890 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
288a0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
288b0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
288c0 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
288d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
288e0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
288f0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
28900 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28910 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
28920 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
28930 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
28940 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
28950 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
28960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
28970 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
28980 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
28990 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
289a0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
289b0 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
289c0 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
289d0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
289e0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
289f0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
28a00 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
28a10 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
28a20 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
28a30 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
28a40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
28a50 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
28a60 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
28a70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
28a80 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
28a90 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
28aa0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
28ab0 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
28ac0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
28ad0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
28ae0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
28af0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
28b00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
28b10 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
28b20 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
28b30 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
28b40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
28b50 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
28b60 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
28b70 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
28b80 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
28b90 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
28ba0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
28bb0 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
28bc0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
28bd0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
28be0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
28bf0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
28c00 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
28c10 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
28c20 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
28c30 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
28c40 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
28c50 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
28c60 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
28c70 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
28c80 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
28c90 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
28ca0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
28cb0 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
28cc0 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
28cd0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
28ce0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
28cf0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
28d00 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
28d10 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
28d20 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
28d30 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
28d40 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
28d50 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
28d60 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
28d70 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
28d80 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
28d90 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
28da0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
28db0 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
28dc0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
28dd0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
28de0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
28df0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
28e00 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
28e10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28e20 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
28e30 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
28e40 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
28e50 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
28e60 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
28e70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
28e80 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
28e90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
28ea0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
28eb0 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
28ec0 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
28ed0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
28ee0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28ef0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
28f00 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
28f10 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28f20 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28f30 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
28f40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28f50 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
28f60 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
28f70 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
28f80 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28f90 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
28fa0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
28fb0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
28fc0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
28fd0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
28fe0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
28ff0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
29000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
29010 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
29020 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
29030 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
29040 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
29050 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
29060 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
29070 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29080 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
29090 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
290a0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
290b0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
290c0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
290d0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
290e0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
290f0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
29100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29110 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
29120 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
29130 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
29140 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
29150 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
29160 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
29170 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
29180 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
29190 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
291a0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
291b0 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
291c0 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
291d0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
291e0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
291f0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
29200 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
29210 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
29220 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
29230 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
29240 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
29250 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
29260 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
29270 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
29280 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
29290 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
292a0 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
292b0 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
292c0 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
292d0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
292e0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
292f0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
29300 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
29310 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
29320 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
29330 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
29340 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
29350 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
29360 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
29370 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
29380 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
29390 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
293a0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
293b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
293c0 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
293d0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
293e0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
293f0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
29400 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
29410 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
29420 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
29430 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
29440 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
29450 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
29460 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
29470 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
29480 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
29490 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
294a0 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
294b0 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
294c0 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
294d0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
294e0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
294f0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
29500 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
29510 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
29520 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
29530 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29540 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29550 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
29560 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
29570 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29580 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
29590 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
295a0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
295b0 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
295c0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
295d0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
295e0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
295f0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
29600 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
29610 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
29620 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
29630 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29640 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
29650 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
29660 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
29670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
29680 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
29690 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
296a0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
296b0 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
296c0 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
296d0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
296e0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
296f0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
29700 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
29710 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
29720 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
29730 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
29740 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
29750 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
29760 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
29770 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
29780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29790 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
297a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
297b0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
297c0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
297d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
297e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
297f0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
29800 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
29810 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
29820 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
29830 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
29840 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
29850 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
29860 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
29870 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
29880 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
29890 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
298a0 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
298b0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
298c0 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
298d0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
298e0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
298f0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
29900 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
29910 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
29920 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29930 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
29940 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
29950 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
29960 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29970 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
29980 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
29990 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
299a0 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
299b0 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
299c0 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
299d0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
299e0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
299f0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
29a00 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
29a10 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
29a20 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
29a30 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
29a40 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
29a50 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
29a60 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
29a70 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
29a80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
29a90 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
29aa0 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
29ab0 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
29ac0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
29ad0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
29ae0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
29af0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
29b00 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
29b10 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
29b20 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
29b30 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
29b40 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
29b50 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
29b60 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
29b70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
29b80 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
29b90 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
29ba0 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
29bb0 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
29bc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29bd0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
29be0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
29bf0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
29c00 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
29c10 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
29c20 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
29c30 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
29c40 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
29c50 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
29c60 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
29c70 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
29c80 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
29c90 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
29ca0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
29cb0 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
29cc0 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
29cd0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
29ce0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
29cf0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
29d00 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
29d10 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
29d20 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
29d30 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
29d40 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
29d50 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
29d60 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
29d70 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
29d80 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
29d90 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
29da0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
29db0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
29dc0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
29dd0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
29de0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
29df0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
29e00 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
29e10 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
29e20 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
29e30 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
29e40 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
29e50 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
29e60 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
29e70 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
29e80 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
29e90 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
29ea0 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
29eb0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
29ec0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
29ed0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
29ee0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
29ef0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
29f00 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
29f10 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
29f20 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
29f30 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
29f40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
29f50 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
29f60 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
29f70 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
29f80 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
29f90 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
29fa0 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
29fb0 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
29fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29fd0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
29fe0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
29ff0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2a000 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2a010 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2a020 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2a030 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2a040 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2a050 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2a060 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2a070 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2a080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a090 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2a0a0 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2a0b0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2a0c0 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2a0d0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2a0e0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2a0f0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2a100 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2a110 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2a120 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a130 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2a140 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2a150 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2a160 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2a170 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2a180 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2a190 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2a1a0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2a1b0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2a1c0 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2a1d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a1e0 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2a1f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2a200 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2a210 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2a220 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2a230 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2a240 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2a250 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2a260 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2a270 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2a280 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2a290 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2a2a0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2a2b0 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2a2c0 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2a2d0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2a2e0 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2a2f0 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2a300 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2a310 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2a320 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2a330 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2a340 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2a350 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2a360 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2a370 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2a380 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2a390 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2a3a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2a3b0 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2a3c0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2a3d0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2a3e0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2a3f0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2a400 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2a410 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2a420 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2a430 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2a440 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2a450 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2a460 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2a470 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2a480 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2a490 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2a4a0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2a4b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2a4c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2a4d0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2a4e0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2a4f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2a500 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2a510 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2a520 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2a530 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2a540 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2a550 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2a560 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2a570 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2a580 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2a590 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
2a5a0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
2a5b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
2a5c0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
2a5d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a5e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
2a5f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
2a600 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
2a610 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
2a620 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2a630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a640 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
2a650 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
2a660 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
2a670 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
2a680 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
2a690 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
2a6a0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
2a6b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2a6c0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2a6d0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2a6e0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2a6f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a700 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2a710 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2a720 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2a730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2a740 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2a750 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2a760 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2a770 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2a780 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2a790 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2a7a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a7b0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2a7c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a7d0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2a7e0 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2a7f0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2a800 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2a810 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2a820 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2a830 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2a840 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2a850 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a860 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2a870 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a880 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2a890 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2a8a0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2a8b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2a8c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2a8d0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2a8e0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2a8f0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2a900 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a910 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2a920 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2a930 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2a940 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2a950 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2a960 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2a970 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2a980 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2a990 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2a9a0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2a9b0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2a9c0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2a9d0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2a9e0 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2a9f0 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2aa00 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2aa10 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2aa20 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2aa30 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2aa40 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2aa50 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2aa60 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2aa70 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2aa80 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2aa90 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2aaa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2aab0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2aac0 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2aad0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2aae0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2aaf0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2ab00 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2ab10 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2ab20 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2ab30 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2ab40 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2ab50 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2ab60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2ab70 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2ab80 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2ab90 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2aba0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2abb0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2abc0 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2abd0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2abe0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2abf0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2ac00 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2ac10 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2ac20 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2ac30 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2ac40 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2ac50 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2ac60 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2ac70 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2ac80 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2ac90 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2aca0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2acb0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2acc0 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2acd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2ace0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2acf0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2ad00 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2ad10 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2ad20 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2ad30 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2ad40 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2ad50 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2ad60 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2ad70 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2ad80 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2ad90 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2ada0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2adb0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2adc0 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2add0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2ade0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2adf0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2ae00 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2ae10 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2ae20 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2ae30 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2ae40 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2ae50 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2ae60 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2ae70 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2ae80 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2ae90 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2aea0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2aeb0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2aec0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2aed0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aee0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2aef0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2af00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2af10 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2af20 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2af30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2af40 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2af50 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2af60 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2af70 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2af80 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2af90 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2afa0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2afb0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2afc0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2afd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2afe0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2aff0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2b000 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2b010 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2b020 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2b030 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2b040 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2b050 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2b060 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2b070 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2b080 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2b090 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2b0a0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2b0b0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2b0c0 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2b0d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2b0e0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2b0f0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2b100 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2b110 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2b120 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2b130 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2b140 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2b150 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2b160 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2b170 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b180 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2b190 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2b1a0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2b1b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2b1c0 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2b1d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2b1e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2b1f0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2b200 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2b210 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2b220 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2b230 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2b240 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2b250 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2b260 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2b270 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2b280 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2b290 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b2a0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2b2b0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2b2c0 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2b2d0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2b2e0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2b2f0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2b300 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2b310 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2b320 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2b330 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2b340 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2b350 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2b360 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2b370 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2b380 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2b390 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2b3a0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2b3b0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2b3c0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2b3d0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2b3e0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2b3f0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2b400 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2b410 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2b420 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2b430 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2b440 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2b450 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2b460 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2b470 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2b480 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2b490 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2b4a0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2b4b0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2b4c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2b4d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2b4e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2b4f0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2b500 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2b510 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2b520 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2b530 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2b540 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2b550 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2b560 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2b570 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2b580 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2b590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2b5a0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2b5b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2b5c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2b5d0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2b5e0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2b5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2b600 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2b610 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b620 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2b630 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2b640 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2b650 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2b660 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2b670 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2b680 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2b690 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2b6a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b6b0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2b6c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2b6d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2b6e0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2b6f0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2b700 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2b710 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2b720 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2b730 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b740 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2b750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b760 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2b770 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2b780 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2b790 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2b7a0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2b7b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b7c0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2b7d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2b7e0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2b7f0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2b800 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2b810 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2b820 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2b830 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b840 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2b850 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2b860 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2b870 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2b880 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2b890 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2b8a0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2b8b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2b8c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2b8d0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2b8e0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2b8f0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2b900 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2b910 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2b920 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2b930 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2b940 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2b950 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2b960 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2b970 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2b980 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2b990 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2b9a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2b9b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2b9c0 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2b9d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b9e0 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2b9f0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2ba00 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2ba10 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2ba20 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2ba30 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2ba40 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2ba50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ba60 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2ba70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2ba80 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2ba90 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2baa0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2bab0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2bac0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2bad0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2bae0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2baf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bb00 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2bb10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2bb20 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2bb30 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2bb40 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2bb50 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2bb60 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2bb70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2bb80 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2bb90 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2bba0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2bbb0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2bbc0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2bbd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2bbe0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2bbf0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2bc00 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2bc10 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2bc20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2bc30 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2bc40 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2bc50 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2bc60 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2bc70 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2bc80 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2bc90 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2bca0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bcb0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2bcc0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2bcd0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2bce0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2bcf0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2bd00 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2bd10 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2bd20 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2bd30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2bd40 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2bd50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2bd60 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2bd70 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2bd80 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2bd90 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2bda0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2bdb0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2bdc0 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2bdd0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2bde0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2bdf0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2be00 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2be10 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2be20 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2be30 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2be40 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2be50 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2be60 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2be70 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2be80 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2be90 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2bea0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2beb0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2bec0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2bed0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2bee0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2bef0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2bf00 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2bf10 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2bf20 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2bf30 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2bf40 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2bf50 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2bf60 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2bf70 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2bf80 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2bf90 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2bfa0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2bfb0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2bfc0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2bfd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
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 42 4c 4f 42 20 20     <td>   BLOB  
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 49 4e 54 45 47 45   <tr><td> INTEGE
2c030 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
2c040 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
2c050 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
2c060 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
2c070 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2c080 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
2c090 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
2c0a0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
2c0b0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2c0c0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2c0d0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
2c0e0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
2c0f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2c100 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2c110 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2c120 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
2c130 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2c140 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
2c150 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2c160 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2c170 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
2c180 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
2c190 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2c1a0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
2c1b0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
2c1c0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2c1d0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
2c1e0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2c1f0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
2c200 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2c210 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
2c220 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2c230 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2c240 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2c250 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2c260 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2c270 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
2c280 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
2c290 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
2c2a0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2c2b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2c2c0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2c2d0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
2c2e0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2c2f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
2c300 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
2c310 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
2c320 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
2c330 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
2c340 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
2c350 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
2c360 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
2c370 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
2c380 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
2c390 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
2c3a0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
2c3b0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
2c3c0 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
2c3d0 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
2c3e0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
2c3f0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
2c400 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
2c410 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
2c420 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
2c430 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
2c440 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
2c450 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
2c460 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
2c470 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
2c480 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
2c490 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
2c4a0 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
2c4b0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
2c4c0 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
2c4d0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c4e0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
2c4f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c500 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
2c510 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2c520 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
2c530 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
2c540 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
2c550 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
2c560 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
2c570 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
2c580 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
2c590 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
2c5a0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c5b0 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
2c5c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c5d0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
2c5e0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2c5f0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
2c600 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
2c610 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
2c620 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
2c630 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
2c640 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
2c650 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
2c660 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
2c670 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
2c680 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c690 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2c6a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2c6b0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2c6c0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
2c6d0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
2c6e0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
2c6f0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2c700 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2c710 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
2c720 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
2c730 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2c740 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2c750 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
2c760 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2c770 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2c780 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2c790 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
2c7a0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
2c7b0 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
2c7c0 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
2c7d0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
2c7e0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
2c7f0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
2c800 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
2c810 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
2c820 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
2c830 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2c840 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
2c850 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
2c860 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
2c870 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
2c880 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
2c890 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
2c8a0 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
2c8b0 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
2c8c0 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
2c8d0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
2c8e0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
2c8f0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
2c900 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
2c910 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
2c920 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
2c930 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
2c940 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
2c950 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
2c960 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2c970 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
2c980 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
2c990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
2c9a0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2c9b0 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
2c9c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2c9d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2c9e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2c9f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2ca00 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
2ca10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ca20 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
2ca30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ca40 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
2ca50 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2ca60 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
2ca70 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
2ca80 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2ca90 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
2caa0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cab0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
2cac0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2cad0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
2cae0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
2caf0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
2cb00 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
2cb10 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
2cb20 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
2cb30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2cb40 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
2cb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2cb60 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
2cb70 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
2cb80 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
2cb90 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
2cba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2cbb0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2cbc0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
2cbd0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
2cbe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2cbf0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
2cc00 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
2cc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2cc20 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
2cc30 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2cc40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
2cc50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
2cc60 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
2cc70 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
2cc80 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
2cc90 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
2cca0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
2ccb0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
2ccc0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2ccd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2cce0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2ccf0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
2cd00 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
2cd10 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
2cd20 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
2cd30 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
2cd40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2cd50 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
2cd60 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
2cd70 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
2cd80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2cd90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
2cda0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
2cdb0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
2cdc0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2cdd0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
2cde0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
2cdf0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2ce00 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
2ce10 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
2ce20 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
2ce30 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
2ce40 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
2ce50 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
2ce60 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
2ce70 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
2ce80 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2ce90 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
2cea0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
2ceb0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2cec0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
2ced0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
2cee0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
2cef0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
2cf00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cf10 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
2cf20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2cf30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2cf40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
2cf50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cf60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2cf70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2cf80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cf90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
2cfa0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2cfb0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2cfc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2cfd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2cfe0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2cff0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d000 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
2d010 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2d020 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2d030 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2d040 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
2d050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d060 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
2d070 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2d080 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
2d090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d0a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2d0b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d0c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
2d0d0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
2d0e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2d0f0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
2d100 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d110 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
2d120 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d140 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
2d150 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
2d160 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
2d170 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2d180 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
2d190 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
2d1a0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d1b0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
2d1c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
2d1d0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
2d1e0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
2d1f0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
2d200 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
2d210 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
2d220 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
2d230 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
2d240 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
2d250 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
2d260 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
2d270 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
2d280 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
2d290 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
2d2a0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2d2b0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
2d2c0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
2d2d0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
2d2e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
2d2f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
2d300 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d310 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
2d320 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
2d330 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
2d340 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
2d350 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2d360 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
2d370 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
2d380 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
2d390 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
2d3a0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
2d3b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d3c0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
2d3d0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
2d3e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
2d3f0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2d400 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
2d410 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
2d420 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
2d430 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
2d440 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
2d450 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
2d460 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
2d470 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
2d480 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2d490 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
2d4a0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
2d4b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
2d4c0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
2d4d0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
2d4e0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
2d4f0 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
2d500 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2d510 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
2d520 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d530 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2d540 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
2d550 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
2d560 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2d570 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2d580 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2d590 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
2d5a0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
2d5b0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
2d5c0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
2d5d0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
2d5e0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69  corruption..*/.i
2d5f0 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
2d600 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
2d610 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d620 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2d630 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2d640 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
2d650 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2d660 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
2d670 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
2d680 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
2d690 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
2d6a0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
2d6b0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
2d6c0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
2d6d0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
2d6e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
2d6f0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
2d700 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
2d710 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
2d720 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2d730 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
2d740 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
2d750 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
2d760 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
2d770 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2d780 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
2d790 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
2d7a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2d7b0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2d7c0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
2d7d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d7e0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
2d7f0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
2d800 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
2d810 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2d820 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2d830 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2d840 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2d850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d860 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
2d870 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
2d880 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
2d890 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
2d8a0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
2d8b0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
2d8c0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
2d8d0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
2d8e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
2d8f0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
2d900 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2d910 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
2d920 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
2d930 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
2d940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d950 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
2d960 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
2d970 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2d980 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
2d990 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
2d9a0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2d9b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2d9c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
2d9d0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2d9e0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
2d9f0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
2da00 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
2da10 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2da20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
2da30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
2da40 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
2da50 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2da60 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
2da70 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
2da80 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
2da90 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
2daa0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
2dab0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
2dac0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2dad0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2dae0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
2daf0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
2db00 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2db10 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
2db20 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
2db30 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
2db40 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
2db50 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
2db60 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
2db70 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
2db80 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
2db90 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
2dba0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2dbb0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
2dbc0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
2dbd0 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
2dbe0 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
2dbf0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
2dc00 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
2dc10 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
2dc20 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
2dc30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2dc40 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
2dc50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
2dc60 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
2dc70 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
2dc80 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
2dc90 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
2dca0 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
2dcb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
2dcc0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2dcd0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2dce0 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
2dcf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2dd00 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
2dd10 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
2dd20 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
2dd30 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
2dd40 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
2dd50 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
2dd60 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
2dd70 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2dd80 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2dd90 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
2dda0 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
2ddb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ddc0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2ddd0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
2dde0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2ddf0 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
2de00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
2de10 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
2de20 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
2de30 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
2de40 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
2de50 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
2de60 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
2de70 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
2de80 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
2de90 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
2dea0 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
2deb0 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
2dec0 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
2ded0 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
2dee0 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
2def0 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
2df00 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
2df10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
2df20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
2df30 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
2df40 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
2df50 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
2df60 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
2df70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
2df80 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
2df90 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
2dfa0 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
2dfb0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
2dfc0 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
2dfd0 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
2dfe0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
2dff0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2e000 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
2e010 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
2e020 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
2e030 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
2e040 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
2e050 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
2e060 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2e070 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
2e080 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
2e090 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
2e0a0 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
2e0b0 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
2e0c0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
2e0d0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2e0e0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2e0f0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
2e100 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
2e110 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
2e120 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
2e130 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
2e140 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
2e150 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
2e160 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
2e170 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e180 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
2e190 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
2e1a0 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
2e1b0 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
2e1c0 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
2e1d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
2e1e0 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
2e1f0 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
2e200 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
2e210 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
2e220 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
2e230 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
2e240 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
2e250 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2e260 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
2e270 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
2e280 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
2e290 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
2e2a0 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
2e2b0 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
2e2c0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
2e2d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
2e2e0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2e2f0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
2e300 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
2e310 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
2e320 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
2e330 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
2e340 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
2e350 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
2e360 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
2e370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e380 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
2e390 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
2e3a0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
2e3b0 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
2e3c0 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
2e3d0 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
2e3e0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
2e3f0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
2e400 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
2e410 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
2e420 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e430 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
2e440 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
2e450 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
2e460 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
2e470 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
2e480 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
2e490 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
2e4a0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
2e4b0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
2e4c0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
2e4d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
2e4e0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
2e4f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
2e500 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2e510 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2e520 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
2e530 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2e540 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
2e550 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
2e560 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
2e570 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
2e580 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2e590 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
2e5a0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
2e5b0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
2e5c0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2e5d0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
2e5e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
2e5f0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
2e600 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
2e610 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
2e620 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
2e630 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
2e640 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
2e650 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
2e660 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
2e670 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
2e680 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
2e690 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
2e6a0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
2e6b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2e6c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2e6d0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
2e6e0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
2e6f0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
2e700 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2e710 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2e720 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
2e730 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
2e740 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
2e750 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
2e760 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
2e770 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
2e780 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
2e790 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
2e7a0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
2e7b0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
2e7c0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
2e7d0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2e7e0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2e7f0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
2e800 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
2e810 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
2e820 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
2e830 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
2e840 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
2e850 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
2e860 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
2e870 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
2e880 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
2e890 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
2e8a0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
2e8b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2e8c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e8d0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
2e8e0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
2e8f0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
2e900 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
2e910 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
2e920 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
2e930 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
2e940 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
2e950 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
2e960 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
2e970 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
2e980 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
2e990 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
2e9a0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
2e9b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2e9c0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
2e9d0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
2e9e0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
2e9f0 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2ea00 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
2ea10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2ea20 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
2ea30 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
2ea40 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
2ea50 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
2ea60 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
2ea70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
2ea80 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
2ea90 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
2eaa0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
2eab0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2eac0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
2ead0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
2eae0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
2eaf0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
2eb00 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
2eb10 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
2eb20 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
2eb30 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2eb40 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2eb50 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
2eb60 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
2eb70 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
2eb80 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
2eb90 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
2eba0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2ebb0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
2ebc0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
2ebd0 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
2ebe0 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
2ebf0 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
2ec00 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
2ec10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ec20 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
2ec30 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
2ec40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2ec50 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
2ec60 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
2ec70 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
2ec80 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
2ec90 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
2eca0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
2ecb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ecc0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
2ecd0 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
2ece0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2ecf0 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
2ed00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2ed10 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
2ed20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ed30 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2ed40 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2ed50 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2ed60 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2ed70 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2ed80 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2ed90 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2eda0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2edb0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2edc0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2edd0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2ede0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2edf0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2ee00 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2ee10 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2ee20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2ee30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
2ee40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2ee50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
2ee60 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2ee70 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2ee80 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2ee90 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2eea0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2eeb0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2eec0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2eed0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2eee0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2eef0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2ef00 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2ef10 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2ef20 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
2ef30 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ef40 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2ef50 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2ef60 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2ef70 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2ef80 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2ef90 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2efa0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2efb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2efc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2efd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2efe0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2eff0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2f000 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2f010 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2f020 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2f030 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2f040 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2f050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2f060 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2f070 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f080 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2f090 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2f0a0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2f0b0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2f0c0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2f0d0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2f0e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2f0f0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2f100 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f110 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2f120 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f130 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2f140 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2f150 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2f160 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2f170 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2f180 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2f190 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2f1a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f1b0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2f1c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f1d0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2f1e0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2f1f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2f200 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2f210 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2f220 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2f230 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2f240 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2f250 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2f260 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2f270 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2f280 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2f290 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2f2a0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2f2b0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2f2c0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2f2d0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2f2e0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2f2f0 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2f300 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2f310 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2f320 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2f330 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2f340 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2f350 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2f360 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2f370 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2f380 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2f390 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2f3a0 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
2f3b0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2f3c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
2f3d0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
2f3e0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
2f3f0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2f400 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
2f410 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2f420 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2f430 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
2f440 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
2f450 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
2f460 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
2f470 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2f480 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
2f490 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
2f4a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2f4b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
2f4c0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
2f4d0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
2f4e0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2f4f0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2f500 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2f510 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2f520 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2f530 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2f540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2f550 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2f560 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2f570 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2f580 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2f590 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2f5a0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2f5b0 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2f5c0 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2f5d0 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2f5e0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2f5f0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2f600 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2f610 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2f620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2f630 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2f640 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2f650 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2f660 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2f670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2f680 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2f690 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2f6a0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2f6b0 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2f6c0 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2f6d0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2f6e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2f6f0 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2f700 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2f710 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2f720 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2f730 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2f740 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2f750 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2f760 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2f770 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f780 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2f790 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2f7a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2f7b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2f7c0 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2f7d0 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2f7e0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2f7f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2f800 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f810 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2f820 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2f830 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f840 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2f850 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2f860 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2f870 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f880 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2f890 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2f8a0 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2f8b0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2f8c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2f8d0 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2f8e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2f8f0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2f900 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2f910 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2f920 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2f930 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2f940 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f950 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2f960 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2f970 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2f980 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2f990 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2f9a0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2f9b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f9c0 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2f9d0 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2f9e0 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2f9f0 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2fa00 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2fa10 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2fa20 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2fa30 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2fa40 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2fa50 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2fa60 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2fa70 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2fa80 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2fa90 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2faa0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2fab0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2fac0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2fad0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2fae0 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2faf0 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2fb00 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2fb10 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2fb20 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2fb30 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2fb40 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2fb50 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2fb60 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2fb70 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2fb80 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2fb90 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2fba0 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2fbb0 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2fbc0 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2fbd0 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2fbe0 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2fbf0 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2fc00 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2fc10 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2fc20 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2fc30 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2fc40 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2fc50 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2fc60 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2fc70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2fc80 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2fc90 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2fca0 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2fcb0 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2fcc0 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2fcd0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2fce0 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2fcf0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2fd00 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2fd10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2fd20 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2fd30 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2fd40 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2fd50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fd60 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2fd70 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2fd80 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2fd90 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2fda0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2fdb0 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2fdc0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2fdd0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2fde0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2fdf0 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2fe00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2fe10 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2fe20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2fe30 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
2fe40 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2fe50 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
2fe60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2fe70 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2fe80 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
2fe90 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2fea0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
2feb0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2fec0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2fed0 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
2fee0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2fef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2ff00 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
2ff10 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
2ff20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
2ff30 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
2ff40 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
2ff50 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
2ff60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ff70 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
2ff80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ff90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2ffa0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
2ffb0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2ffc0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ffd0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2ffe0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
2fff0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
30000 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
30010 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
30020 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
30030 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30040 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
30050 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
30060 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
30070 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
30080 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
30090 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
300a0 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
300b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
300c0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
300d0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
300e0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
300f0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
30100 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
30110 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
30120 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
30130 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30140 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
30150 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
30160 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
30170 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
30180 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
30190 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
301a0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
301b0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
301c0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
301d0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
301e0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
301f0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
30200 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
30210 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
30220 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30230 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
30240 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
30250 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
30260 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
30270 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
30280 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30290 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
302a0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
302b0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
302c0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
302d0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
302e0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
302f0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
30300 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
30310 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
30320 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
30330 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
30340 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
30350 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
30360 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
30370 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
30380 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
30390 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
303a0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
303b0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
303c0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
303d0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
303e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
303f0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
30400 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
30410 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
30420 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
30430 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
30440 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
30450 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
30460 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
30470 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
30480 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
30490 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
304a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
304b0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
304c0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
304d0 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
304e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
304f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
30500 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
30510 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
30520 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
30530 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
30540 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
30550 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
30560 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
30570 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
30580 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30590 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
305a0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
305b0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
305c0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
305d0 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
305e0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
305f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
30600 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
30610 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
30620 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
30630 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30640 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
30650 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
30660 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
30670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
30680 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
30690 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
306a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
306b0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
306c0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
306d0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
306e0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
306f0 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
30700 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
30710 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
30720 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
30730 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
30740 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
30750 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
30760 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
30770 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
30780 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
30790 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
307a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
307b0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
307c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
307d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
307e0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
307f0 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
30800 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
30810 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
30820 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
30830 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
30840 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
30850 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
30860 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
30870 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
30880 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
30890 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
308a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
308b0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
308c0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
308d0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
308e0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
308f0 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
30900 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
30910 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
30920 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
30930 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
30940 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30950 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
30960 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
30970 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
30980 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
30990 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
309a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
309b0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
309c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
309d0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
309e0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
309f0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
30a00 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
30a10 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
30a20 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30a30 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
30a40 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
30a50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30a60 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
30a70 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
30a80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
30a90 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
30aa0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
30ab0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
30ac0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
30ad0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
30ae0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
30af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
30b00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
30b10 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
30b20 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
30b30 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
30b40 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
30b50 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
30b60 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
30b70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
30b80 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
30b90 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
30ba0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
30bb0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
30bc0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
30bd0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
30be0 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
30bf0 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
30c00 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
30c10 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
30c20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
30c30 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
30c40 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
30c50 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
30c60 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
30c70 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
30c80 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
30c90 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
30ca0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
30cb0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
30cc0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
30cd0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
30ce0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
30cf0 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
30d00 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
30d10 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
30d20 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
30d30 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
30d40 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
30d50 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
30d60 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
30d70 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
30d80 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
30d90 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30da0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
30db0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
30dc0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
30dd0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
30de0 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
30df0 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
30e00 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
30e10 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
30e20 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
30e30 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
30e40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
30e50 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
30e60 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
30e70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
30e80 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
30e90 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
30ea0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30eb0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
30ec0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
30ed0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
30ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
30ef0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
30f00 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
30f10 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
30f20 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
30f30 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
30f40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
30f50 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
30f60 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
30f70 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
30f80 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
30f90 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
30fa0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
30fb0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
30fc0 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
30fd0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
30fe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30ff0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
31000 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
31010 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
31020 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
31030 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
31040 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
31050 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
31060 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
31070 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31080 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
31090 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
310a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
310b0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
310c0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
310d0 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
310e0 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
310f0 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
31100 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
31110 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
31120 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
31130 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
31140 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
31150 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
31160 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
31170 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
31180 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
31190 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
311a0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
311b0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
311c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
311d0 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
311e0 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
311f0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
31200 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
31210 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
31220 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
31230 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
31240 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
31250 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
31260 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
31270 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
31280 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
31290 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
312a0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
312b0 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
312c0 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
312d0 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
312e0 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
312f0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
31300 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
31310 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
31320 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
31330 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
31340 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
31350 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
31360 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
31370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
31380 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31390 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
313a0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
313b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
313c0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
313d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
313e0 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
313f0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
31400 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
31410 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
31420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
31430 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
31440 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
31450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31460 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
31470 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
31480 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
31490 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
314a0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
314b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
314c0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
314d0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
314e0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
314f0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
31500 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
31510 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
31520 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
31530 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
31540 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
31550 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
31560 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
31570 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
31580 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
31590 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
315a0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
315b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
315c0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
315d0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
315e0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
315f0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
31600 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
31610 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
31620 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
31630 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
31640 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
31650 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
31660 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
31670 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
31680 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
31690 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
316a0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
316b0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
316c0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
316d0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
316e0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
316f0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
31700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31710 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
31720 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
31730 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
31740 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
31750 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
31760 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
31770 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
31780 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
31790 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
317a0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
317b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
317c0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
317d0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
317e0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
317f0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
31800 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31810 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
31820 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31830 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
31840 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31850 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
31860 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
31870 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
31880 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
31890 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
318a0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
318b0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
318c0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
318d0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
318e0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
318f0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
31900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31910 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
31920 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
31930 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
31940 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
31950 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
31960 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31970 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
31980 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
31990 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
319a0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
319b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
319c0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
319d0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
319e0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
319f0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
31a00 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
31a10 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
31a20 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
31a30 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
31a40 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31a50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
31a60 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
31a70 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
31a80 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
31a90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31aa0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31ab0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
31ac0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
31ad0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
31ae0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
31af0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
31b00 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
31b10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31b20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
31b30 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
31b40 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
31b50 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
31b60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
31b70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
31b80 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
31b90 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
31ba0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
31bb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
31bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31bd0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31be0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31bf0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
31c00 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
31c10 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
31c20 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
31c30 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
31c40 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
31c50 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
31c60 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
31c70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
31c80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31c90 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
31ca0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31cb0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
31cc0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
31cd0 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
31ce0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
31cf0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
31d00 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
31d10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31d20 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
31d30 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
31d40 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
31d50 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
31d60 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
31d70 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
31d80 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
31d90 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
31da0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31db0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
31dc0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
31dd0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
31de0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
31df0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
31e00 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
31e10 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
31e20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
31e30 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
31e40 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
31e50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
31e60 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
31e70 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
31e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31e90 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
31ea0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
31eb0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
31ec0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
31ed0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
31ee0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31ef0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
31f00 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
31f10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31f20 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
31f30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31f40 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
31f50 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
31f60 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
31f70 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
31f80 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
31f90 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
31fa0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
31fb0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
31fc0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
31fd0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
31fe0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
31ff0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
32000 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32010 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
32020 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
32030 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
32040 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
32050 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
32060 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
32070 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
32080 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
32090 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
320a0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
320b0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
320c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
320d0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
320e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
320f0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
32100 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
32110 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
32120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32130 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32140 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
32150 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
32160 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
32170 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
32180 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
32190 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
321a0 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
321b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
321c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
321d0 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
321e0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
321f0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
32200 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
32210 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
32220 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
32230 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32240 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32250 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32260 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
32270 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
32280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32290 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
322a0 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
322b0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
322c0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
322d0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
322e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
322f0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
32300 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32310 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32320 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32330 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32340 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
32350 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
32360 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
32370 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
32380 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32390 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
323a0 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
323b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
323c0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
323d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
323e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
323f0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32400 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32410 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
32420 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32430 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
32440 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
32450 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
32460 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
32470 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
32480 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
32490 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
324a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
324b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
324c0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
324d0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
324e0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
324f0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
32500 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
32510 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
32520 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
32530 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
32540 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
32550 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
32560 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
32570 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
32580 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
32590 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
325a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
325b0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
325c0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
325d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
325e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
325f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32600 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
32610 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
32620 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
32630 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
32640 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
32650 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
32660 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
32670 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
32680 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
32690 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
326a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
326b0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
326c0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
326d0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
326e0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
326f0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
32700 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
32710 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
32720 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32730 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
32740 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
32750 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
32760 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
32770 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
32780 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
32790 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
327a0 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
327b0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
327c0 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
327d0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
327e0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
327f0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
32800 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
32810 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
32820 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
32830 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
32840 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
32850 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
32860 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
32870 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
32880 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
32890 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
328a0 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
328b0 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
328c0 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
328d0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
328e0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
328f0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
32900 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32910 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32920 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
32930 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
32940 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
32950 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
32960 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
32970 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
32980 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
32990 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
329a0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
329b0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
329c0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
329d0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
329e0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
329f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32a00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
32a10 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
32a20 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
32a30 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
32a40 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
32a50 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
32a60 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
32a70 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
32a80 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
32a90 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
32aa0 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
32ab0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
32ac0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
32ad0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
32ae0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
32af0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
32b00 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
32b10 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
32b20 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32b30 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32b40 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32b50 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32b60 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
32b70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32b80 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
32b90 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
32ba0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
32bb0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
32bc0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
32bd0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
32be0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
32bf0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
32c00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
32c10 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
32c20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32c30 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
32c40 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
32c50 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
32c60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32c70 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32c80 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
32c90 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
32ca0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32cb0 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
32cc0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
32cd0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
32ce0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
32cf0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
32d00 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
32d10 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
32d20 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
32d30 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
32d40 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
32d50 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
32d60 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
32d70 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
32d80 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
32d90 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
32da0 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
32db0 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
32dc0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
32dd0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
32de0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
32df0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
32e00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
32e10 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
32e20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
32e30 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
32e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
32e50 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
32e60 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
32e70 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
32e80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32e90 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
32ea0 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
32eb0 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
32ec0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
32ed0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
32ee0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32ef0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
32f00 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
32f10 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
32f20 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
32f30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
32f40 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32f50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
32f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32f70 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
32f80 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
32f90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
32fa0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
32fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32fc0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
32fd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32fe0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
32ff0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
33000 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
33010 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33020 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
33030 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
33040 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
33050 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
33060 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
33070 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
33080 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33090 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
330a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
330b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
330c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
330d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
330e0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
330f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
33100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33110 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
33120 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
33130 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33140 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
33150 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
33160 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
33170 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
33180 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33190 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
331a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
331b0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
331c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
331d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
331e0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
331f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33200 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
33210 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
33220 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33230 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
33240 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
33250 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
33260 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
33270 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
33280 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
33290 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
332a0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
332b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
332c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
332d0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
332e0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
332f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
33300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33310 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33320 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33330 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33340 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33350 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
33360 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
33370 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
33380 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
33390 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
333a0 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
333b0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
333c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
333d0 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
333e0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
333f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
33400 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
33410 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
33420 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
33430 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
33440 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
33450 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
33460 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
33470 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
33480 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
33490 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
334a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
334b0 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
334c0 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
334d0 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
334e0 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
334f0 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
33500 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
33510 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
33520 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
33530 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
33540 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
33550 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
33560 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
33570 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
33580 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
33590 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
335a0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
335b0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
335c0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
335d0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
335e0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
335f0 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
33600 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
33610 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
33620 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
33630 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
33640 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
33650 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
33660 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
33670 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
33680 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
33690 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
336a0 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
336b0 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
336c0 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
336d0 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
336e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
336f0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
33700 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
33710 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
33720 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
33730 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
33740 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
33750 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
33760 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
33770 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
33780 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33790 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
337a0 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
337b0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
337c0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
337d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
337e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
337f0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
33800 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
33810 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
33820 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33830 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
33840 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
33850 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
33860 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
33870 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
33880 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
33890 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
338a0 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
338b0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
338c0 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
338d0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
338e0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
338f0 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
33900 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
33910 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
33920 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
33930 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
33940 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
33950 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
33960 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
33970 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
33980 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
33990 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
339a0 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
339b0 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
339c0 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
339d0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
339e0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
339f0 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
33a00 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
33a10 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33a20 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
33a30 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
33a40 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
33a50 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
33a60 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
33a70 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
33a80 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
33a90 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
33aa0 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
33ab0 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
33ac0 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
33ad0 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
33ae0 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
33af0 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
33b00 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
33b10 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
33b20 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
33b30 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
33b40 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
33b50 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
33b60 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
33b70 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
33b80 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
33b90 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
33ba0 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
33bb0 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
33bc0 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
33bd0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
33be0 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
33bf0 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
33c00 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
33c10 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
33c20 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
33c30 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
33c40 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
33c50 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
33c60 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
33c70 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
33c80 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
33c90 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
33ca0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
33cb0 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
33cc0 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
33cd0 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
33ce0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
33cf0 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
33d00 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
33d10 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
33d20 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
33d30 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
33d40 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
33d50 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
33d60 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
33d70 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
33d80 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33d90 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
33da0 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
33db0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
33dc0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
33dd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
33de0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
33df0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
33e00 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
33e10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33e20 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
33e30 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
33e40 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
33e50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
33e60 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
33e70 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
33e80 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
33e90 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
33ea0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
33eb0 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
33ec0 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
33ed0 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
33ee0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
33ef0 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
33f00 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
33f10 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
33f20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
33f30 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
33f40 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
33f50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
33f60 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
33f70 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
33f80 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
33f90 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33fa0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
33fb0 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
33fc0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
33fd0 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
33fe0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33ff0 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
34000 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
34010 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
34020 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
34030 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
34040 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
34050 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34060 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
34070 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
34080 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
34090 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
340a0 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
340b0 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
340c0 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
340d0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
340e0 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
340f0 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
34100 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
34110 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
34120 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
34130 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
34140 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
34150 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
34160 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34170 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
34180 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34190 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
341a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
341b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
341c0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
341d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
341e0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
341f0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
34200 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
34210 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
34220 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
34230 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  nst void*).);.in
34240 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
34250 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20  _collation_v2(. 
34260 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34270 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34280 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
34290 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
342a0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
342b0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
342c0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
342d0 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
342e0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
342f0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34300 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34310 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
34320 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
34330 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
34340 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34350 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34360 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34370 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34380 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
34390 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
343a0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
343b0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
343c0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
343d0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
343e0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
343f0 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
34400 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
34410 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
34420 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
34430 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
34440 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
34450 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
34460 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
34470 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
34480 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
34490 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
344a0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
344b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
344c0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
344d0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
344e0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
344f0 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
34500 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
34510 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
34520 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
34530 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
34540 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
34550 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
34560 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
34570 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
34580 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
34590 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
345a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
345b0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
345c0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
345d0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
345e0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
345f0 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
34600 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
34610 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
34620 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
34630 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
34640 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34650 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
34660 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
34670 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
34680 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34690 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
346a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
346b0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
346c0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
346d0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
346e0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
346f0 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
34700 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
34710 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
34720 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34730 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
34740 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
34750 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
34760 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
34770 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
34780 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
34790 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
347a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
347b0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
347c0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
347d0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
347e0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
347f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
34800 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
34810 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
34820 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
34830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34840 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
34850 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34860 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
34870 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34880 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34890 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  _v2()]..*/.int s
348a0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
348b0 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74  _needed(.  sqlit
348c0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a  e3*, .  void*, .
348d0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
348e0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
348f0 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72  xtRep,const char
34900 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
34910 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
34920 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  ed16(.  sqlite3*
34930 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f  , .  void*,.  vo
34940 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
34950 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
34960 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  p,const void*).)
34970 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  ;..#ifdef SQLITE
34980 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a  _HAS_CODEC./*.**
34990 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
349a0 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
349b0 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
349c0 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
349d0 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
349e0 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
349f0 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
34a00 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
34a10 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
34a20 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
34a30 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
34a40 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
34a50 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
34a60 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
34a70 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
34a80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
34a90 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
34aa0 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
34ab0 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
34ac0 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
34ad0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
34ae0 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
34af0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
34b00 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
34b10 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
34b20 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
34b30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
34b40 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
34b50 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
34b60 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
34b70 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
34b80 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
34b90 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
34ba0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
34bb0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
34bc0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
34bd0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
34be0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
34bf0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
34c00 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
34c10 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
34c20 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
34c30 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
34c40 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
34c50 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
34c60 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
34c70 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
34c80 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
34c90 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
34ca0 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
34cb0 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
34cc0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
34cd0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
34ce0 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
34cf0 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20  te_see(.  const 
34d00 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
34d10 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
34d20 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
34d30 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64  .);.#endif..#ifd
34d40 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ef SQLITE_ENABLE
34d50 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65  _CEROD./*.** Spe
34d60 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
34d70 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45  ion key for a CE
34d80 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55  ROD database.  U
34d90 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
34da0 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
34db0 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20   CEROD routines 
34dc0 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f  will work..*/.vo
34dd0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
34de0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
34df0 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
34e00 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
34e10 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
34e20 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
34e30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
34e40 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
34e50 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
34e60 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
34e70 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
34e80 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
34e90 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
34ea0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
34eb0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
34ec0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
34ed0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
34ee0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
34ef0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
34f00 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
34f10 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
34f20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
34f30 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
34f40 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
34f50 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
34f60 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
34f70 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
34f80 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
34f90 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
34fa0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
34fb0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
34fc0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
34fd0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
34fe0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
34ff0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
35000 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
35010 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
35020 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
35030 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
35040 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
35050 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
35060 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
35070 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
35080 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
35090 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
350a0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
350b0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
350c0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
350d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
350e0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
350f0 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
35100 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
35110 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
35120 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
35130 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  aphs..*/.int sql
35140 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b  ite3_sleep(int);
35150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35160 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f  : Name Of The Fo
35170 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d  lder Holding Tem
35180 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a  porary Files.**.
35190 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f  ** ^(If this glo
351a0 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20  bal variable is 
351b0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
351c0 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20   a string which 
351d0 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  is.** the name o
351e0 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e  f a folder (a.k.
351f0 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74  a. directory), t
35200 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72  hen all temporar
35210 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74  y files.** creat
35220 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65  ed by SQLite whe
35230 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
35240 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
35250 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62  | VFS].** will b
35260 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74  e placed in that
35270 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e   directory.)^  ^
35280 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  If this variable
35290 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
352a0 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
352b0 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65  te performs a se
352c0 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72  arch for an appr
352d0 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  opriate.** tempo
352e0 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74  rary file direct
352f0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ory..**.** It is
35300 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35310 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35320 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
35330 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
35340 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
35350 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
35360 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
35370 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
35380 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
35390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
353a0 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
353b0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
353c0 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
353d0 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
353e0 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
353f0 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
35400 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
35410 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
35420 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
35430 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
35440 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
35450 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
35460 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
35470 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
35480 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
35490 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
354a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70  **.** ^The [temp
354b0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
354c0 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
354d0 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
354e0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
354f0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
35500 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
35510 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
35520 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
35530 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70  re,.** the [temp
35540 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
35550 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
35560 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
35570 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
35580 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
35590 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
355a0 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
355b0 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
355c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
355d0 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
355e0 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
355f0 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
35600 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
35610 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
35620 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
35630 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
35640 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
35650 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
35660 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
35670 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
35680 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
35690 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
356a0 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
356b0 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70  use of the [temp
356c0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
356d0 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
356e0 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a  be avoided..**.*
356f0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
35700 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65  dows Runtime use
35710 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d  rs:</b>  The tem
35720 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79  porary directory
35730 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20   must be set.** 
35740 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
35750 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20   [sqlite3_open] 
35760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
35770 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65  _v2].  Otherwise
35780 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61  , various.** fea
35790 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69  tures that requi
357a0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65  re the use of te
357b0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61  mporary files ma
357c0 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73  y fail.  Here is
357d0 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f   an.** example o
357e0 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73  f how to do this
357f0 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20   using C++ with 
35800 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74  the Windows Runt
35810 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ime:.**.** <bloc
35820 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
35830 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20  LPCWSTR zPath = 
35840 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65  Windows::Storage
35850 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74  ::ApplicationDat
35860 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20  a::Current->.** 
35870 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f  &nbsp;     Tempo
35880 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68  raryFolder->Path
35890 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61  ->Data();.** cha
358a0 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d  r zPathBuf&#91;M
358b0 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b  AX_PATH + 1&#93;
358c0 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74  ;.** memset(zPat
358d0 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28  hBuf, 0, sizeof(
358e0 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57  zPathBuf));.** W
358f0 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79  ideCharToMultiBy
35900 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a  te(CP_UTF8, 0, z
35910 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42  Path, -1, zPathB
35920 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68  uf, sizeof(zPath
35930 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  Buf),.** &nbsp; 
35940 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b      NULL, NULL);
35950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70  .** sqlite3_temp
35960 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c  _directory = sql
35970 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73  ite3_mprintf("%s
35980 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a  ", zPathBuf);.**
35990 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
359a0 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ote>.*/.SQLITE_E
359b0 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69  XTERN char *sqli
359c0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
359d0 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ry;../*.** CAPI3
359e0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
359f0 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
35a00 44 61 74 61 62 61 73 65 20 46 69 6c 65 73 0a 2a  Database Files.*
35a10 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
35a20 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
35a30 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
35a40 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
35a50 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
35a60 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
35a70 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
35a80 20 74 68 65 6e 20 61 6c 6c 20 64 61 74 61 62 61   then all databa
35a90 73 65 20 66 69 6c 65 73 0a 2a 2a 20 73 70 65 63  se files.** spec
35aa0 69 66 69 65 64 20 77 69 74 68 20 61 20 72 65 6c  ified with a rel
35ab0 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20 61  ative pathname a
35ac0 6e 64 20 63 72 65 61 74 65 64 20 6f 72 20 61 63  nd created or ac
35ad0 63 65 73 73 65 64 20 62 79 0a 2a 2a 20 53 51 4c  cessed by.** SQL
35ae0 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
35af0 20 62 75 69 6c 74 2d 69 6e 20 77 69 6e 64 6f 77   built-in window
35b00 73 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  s [sqlite3_vfs |
35b10 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61 73   VFS] will be as
35b20 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20 72  sumed.** to be r
35b30 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74 20  elative to that 
35b40 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49 66  directory.)^ ^If
35b50 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
35b60 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  s a NULL.** poin
35b70 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35b80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6c   assumes that al
35b90 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  l database files
35ba0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77 69   specified.** wi
35bb0 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  th a relative pa
35bc0 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61 74  thname are relat
35bd0 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72 65  ive to the curre
35be0 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a 20  nt directory.** 
35bf0 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73 2e  for the process.
35c00 20 20 4f 6e 6c 79 20 74 68 65 20 77 69 6e 64 6f    Only the windo
35c10 77 73 20 56 46 53 20 6d 61 6b 65 73 20 75 73 65  ws VFS makes use
35c20 20 6f 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 0a   of this global.
35c30 2a 2a 20 76 61 72 69 61 62 6c 65 3b 20 69 74 20  ** variable; it 
35c40 69 73 20 69 67 6e 6f 72 65 64 20 62 79 20 74 68  is ignored by th
35c50 65 20 75 6e 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a  e unix VFS..**.*
35c60 2a 20 43 68 61 6e 67 69 6e 67 20 74 68 65 20 76  * Changing the v
35c70 61 6c 75 65 20 6f 66 20 74 68 69 73 20 76 61 72  alue of this var
35c80 69 61 62 6c 65 20 77 68 69 6c 65 20 61 20 64 61  iable while a da
35c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35ca0 6e 20 69 73 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e  n is.** open can
35cb0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 63 6f 72   result in a cor
35cc0 72 75 70 74 20 64 61 74 61 62 61 73 65 2e 0a 2a  rupt database..*
35cd0 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  *.** It is not s
35ce0 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
35cf0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
35d00 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e  ble in more than
35d10 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61   one.** thread a
35d20 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73  t a time.  It is
35d30 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
35d40 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
35d50 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20   variable.** if 
35d60 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
35d70 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
35d80 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61 6d   used at the sam
35d90 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61  e time in a sepa
35da0 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a  rate.** thread..
35db0 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65  ** It is intende
35dc0 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
35dd0 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65  able be set once
35de0 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70  .** as part of p
35df0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
35e00 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65  ation and before
35e10 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
35e20 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65  rface.** routine
35e30 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  s have been call
35e40 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ed and that this
35e50 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e   variable remain
35e60 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68   unchanged.** th
35e70 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  ereafter..**.** 
35e80 5e 54 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65  ^The [data_store
35e90 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35ea0 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68  a] may modify th
35eb0 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20  is variable and 
35ec0 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70  cause.** it to p
35ed0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
35ee0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
35ef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20  lite3_malloc].  
35f00 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a  ^Furthermore,.**
35f10 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
35f20 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
35f30 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65  a] always assume
35f40 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e  s that any strin
35f50 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76  g.** that this v
35f60 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74  ariable points t
35f70 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d  o is held in mem
35f80 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
35f90 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
35fa0 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70  alloc] and the p
35fb0 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70  ragma may attemp
35fc0 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d  t to free that m
35fd0 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b  emory.** using [
35fe0 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a  sqlite3_free]..*
35ff0 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73  * Hence, if this
36000 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64   variable is mod
36010 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20  ified directly, 
36020 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64  either it should
36030 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c   be.** made NULL
36040 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   or made to poin
36050 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
36060 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36070 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72  e3_malloc].** or
36080 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66   else the use of
36090 20 74 68 65 20 5b 64 61 74 61 5f 73 74 6f 72 65   the [data_store
360a0 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
360b0 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f  a] should be avo
360c0 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ided..*/.SQLITE_
360d0 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
360e0 69 74 65 33 5f 64 61 74 61 5f 64 69 72 65 63 74  ite3_data_direct
360f0 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
36100 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
36110 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
36120 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
36130 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
36140 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36150 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
36160 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
36170 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
36180 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
36190 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
361a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
361b0 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
361c0 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
361d0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
361e0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
361f0 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
36200 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
36210 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
36220 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
36230 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
36240 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
36250 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
36260 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
36270 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
36280 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
36290 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
362a0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
362b0 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
362c0 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
362d0 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
362e0 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
362f0 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
36300 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
36310 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
36320 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
36330 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
36340 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
36350 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
36360 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
36370 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
36380 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
36390 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
363a0 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
363b0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
363c0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
363d0 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
363e0 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
363f0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
36400 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
36410 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
36420 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
36430 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
36440 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
36450 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
36460 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
36470 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
36480 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
36490 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
364a0 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
364b0 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  mmit(sqlite3*);.
364c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
364d0 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61   Find The Databa
364e0 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50  se Handle Of A P
364f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
36500 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
36510 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69  ite3_db_handle i
36520 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36530 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
36550 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20  e.** to which a 
36560 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36570 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e  ent] belongs.  ^
36580 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
36590 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74  nnection].** ret
365a0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
365b0 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68  _db_handle is th
365c0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
365d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
365e0 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72  that was the fir
365f0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
36600 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  o the [sqlite3_p
36610 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c  repare_v2()] cal
36620 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e  l (or its varian
36630 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65  ts) that was use
36640 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74  d to.** create t
36650 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  he statement in 
36660 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e  the first place.
36670 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
36680 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73  ite3_db_handle(s
36690 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
366a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
366b0 52 65 74 75 72 6e 20 54 68 65 20 46 69 6c 65 6e  Return The Filen
366c0 61 6d 65 20 46 6f 72 20 41 20 44 61 74 61 62 61  ame For A Databa
366d0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
366e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
366f0 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e  _db_filename(D,N
36700 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36710 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
36720 20 61 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61   a filename.** a
36730 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 64  ssociated with d
36740 61 74 61 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e  atabase N of con
36750 6e 65 63 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65  nection D.  ^The
36760 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
36770 69 6c 65 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e  ile.** has the n
36780 61 6d 65 20 22 6d 61 69 6e 22 2e 20 20 49 66 20  ame "main".  If 
36790 74 68 65 72 65 20 69 73 20 6e 6f 20 61 74 74 61  there is no atta
367a0 63 68 65 64 20 64 61 74 61 62 61 73 65 20 4e 20  ched database N 
367b0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  on the database.
367c0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  ** connection D,
367d0 20 6f 72 20 69 66 20 64 61 74 61 62 61 73 65 20   or if database 
367e0 4e 20 69 73 20 61 20 74 65 6d 70 6f 72 61 72 79  N is a temporary
367f0 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61   or in-memory da
36800 74 61 62 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20  tabase, then.** 
36810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36820 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
36830 2a 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  * ^The filename 
36840 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
36850 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
36860 20 6f 75 74 70 75 74 20 6f 66 20 74 68 65 0a 2a   output of the.*
36870 2a 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20  * xFullPathname 
36880 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 56  method of the [V
36890 46 53 5d 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20  FS].  ^In other 
368a0 77 6f 72 64 73 2c 20 74 68 65 20 66 69 6c 65 6e  words, the filen
368b0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61  ame.** will be a
368c0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 6e  n absolute pathn
368d0 61 6d 65 2c 20 65 76 65 6e 20 69 66 20 74 68 65  ame, even if the
368e0 20 66 69 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a   filename used.*
368f0 2a 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  * to open the da
36900 74 61 62 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c  tabase originall
36910 79 20 77 61 73 20 61 20 55 52 49 20 6f 72 20 72  y was a URI or r
36920 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
36930 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
36940 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65  *sqlite3_db_file
36950 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62  name(sqlite3 *db
36960 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44  , const char *zD
36970 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  bName);../*.** C
36980 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
36990 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ne if a database
369a0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a   is read-only.**
369b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
369c0 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e  _db_readonly(D,N
369d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
369e0 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74  rns 1 if the dat
369f0 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f  abase N.** of co
36a00 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65  nnection D is re
36a10 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74  ad-only, 0 if it
36a20 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20   is read/write, 
36a30 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f  or -1 if N is no
36a40 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  t.** the name of
36a50 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63   a database on c
36a60 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a  onnection D..*/.
36a70 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
36a80 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20  eadonly(sqlite3 
36a90 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
36aa0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
36ab0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
36ac0 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
36ad0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
36ae0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
36af0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
36b00 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
36b10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
36b20 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
36b30 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
36b40 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36b50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
36b60 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
36b70 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
36b80 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
36b90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
36ba0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
36bb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
36bc0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
36bd0 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
36be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
36bf0 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
36c00 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
36c10 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
36c20 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
36c30 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
36c40 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
36c50 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36c60 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
36c70 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
36c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
36c90 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
36ca0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
36cb0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
36cc0 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
36cd0 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
36ce0 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
36cf0 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65  inter..*/.sqlite
36d00 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
36d10 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
36d20 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
36d30 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
36d50 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
36d60 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
36d70 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
36d80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
36d90 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  mit_hook() inter
36da0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
36db0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
36dc0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
36dd0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74  ked whenever a t
36de0 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43  ransaction is [C
36df0 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65  OMMIT | committe
36e00 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c  d]..** ^Any call
36e10 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
36e20 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
36e30 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
36e40 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
36e50 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
36e60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
36e70 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20  ridden..** ^The 
36e80 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36e90 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63  _hook() interfac
36ea0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
36eb0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
36ec0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
36ed0 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e   whenever a tran
36ee0 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c  saction is [ROLL
36ef0 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61  BACK | rolled ba
36f00 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ck]..** ^Any cal
36f10 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
36f20 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
36f30 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36f40 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74  _hook().** for t
36f50 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
36f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
36f70 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54  verridden..** ^T
36f80 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
36f90 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
36fa0 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  gh to the callba
36fb0 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ck..** ^If the c
36fc0 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
36fd0 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
36fe0 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
36ff0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
37000 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
37010 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
37020 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ack..**.** ^The 
37030 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37040 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73  ook(D,C,P) and s
37050 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
37060 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63  hook(D,C,P) func
37070 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20  tions.** return 
37080 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66  the P argument f
37090 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73  rom the previous
370a0 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d   call of the sam
370b0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e  e function.** on
370c0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
370d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
370e0 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a  D, or NULL for.*
370f0 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  * the first call
37100 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69   for each functi
37110 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54  on on D..**.** T
37120 68 65 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f  he commit and ro
37130 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c  llback hook call
37140 62 61 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65  backs are not re
37150 65 6e 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20  entrant..** The 
37160 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
37170 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
37180 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
37190 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
371a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
371b0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
371c0 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
371d0 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
371e0 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
371f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
37200 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
37210 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
37220 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
37230 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
37240 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
37250 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
37260 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
37270 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
37280 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
37290 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
372a0 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68   running any oth
372b0 65 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  er SQL statement
372c0 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c  s, including SEL
372d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a  ECT statements,.
372e0 2a 2a 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c  ** or merely cal
372f0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  ling [sqlite3_pr
37300 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
37310 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
37320 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
37330 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
37340 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
37350 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
37360 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
37370 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52  agraph..**.** ^R
37380 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c  egistering a NUL
37390 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  L function disab
373a0 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  les the callback
373b0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ..**.** ^When th
373c0 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61  e commit hook ca
373d0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
373e0 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
373f0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65   [COMMIT].** ope
37400 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65  ration is allowe
37410 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f  d to continue no
37420 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65  rmally.  ^If the
37430 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20   commit hook.** 
37440 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37450 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d  , then the [COMM
37460 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64  IT] is converted
37470 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43   into a [ROLLBAC
37480 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  K]..** ^The roll
37490 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76  back hook is inv
374a0 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61  oked on a rollba
374b0 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74 73 20  ck that results 
374c0 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a  from a commit.**
374d0 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20   hook returning 
374e0 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61  non-zero, just a
374f0 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69  s it would be wi
37500 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c  th any other rol
37510 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  lback..**.** ^Fo
37520 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
37530 66 20 74 68 69 73 20 41 50 49 2c 20 61 20 74 72  f this API, a tr
37540 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69  ansaction is sai
37550 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a  d to have been.*
37560 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66  * rolled back if
37570 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f   an explicit "RO
37580 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e  LLBACK" statemen
37590 74 20 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f  t is executed, o
375a0 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72  r.** an error or
375b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73   constraint caus
375c0 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72  es an implicit r
375d0 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72  ollback to occur
375e0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
375f0 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e  ck callback is n
37600 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20  ot invoked if a 
37610 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a  transaction is.*
37620 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
37630 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61  rolled back beca
37640 75 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  use the database
37650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
37660 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  losed..**.** See
37670 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
37680 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
37690 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
376a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
376b0 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
376c0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
376d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
376e0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
376f0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
37700 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
37710 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
37720 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
37730 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
37740 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
37750 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37760 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
37770 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
37780 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
37790 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
377a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
377b0 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
377c0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
377d0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
377e0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
377f0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
37800 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
37810 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
37820 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
37830 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
37840 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
37850 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
37860 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
37870 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
37880 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
37890 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
378a0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
378b0 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
378c0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
378d0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
378e0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
378f0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
37900 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
37910 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
37920 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37930 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
37940 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
37950 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
37960 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
37970 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
37980 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
37990 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
379a0 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
379b0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
379c0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
379d0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
379e0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
379f0 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
37a00 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
37a10 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
37a20 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
37a30 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
37a40 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
37a50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
37a60 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
37a70 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
37a80 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
37a90 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
37aa0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37ab0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
37ac0 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
37ad0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
37ae0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
37af0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
37b00 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
37b10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
37b20 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
37b30 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37b40 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
37b50 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
37b60 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
37b70 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
37b80 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
37b90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
37ba0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
37bb0 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
37bc0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
37bd0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
37be0 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
37bf0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
37c00 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
37c10 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
37c20 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
37c30 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
37c40 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
37c50 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
37c60 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
37c70 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
37c80 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
37c90 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
37ca0 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
37cb0 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
37cc0 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
37cd0 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
37ce0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
37cf0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
37d00 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
37d10 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
37d20 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
37d30 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
37d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37d50 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
37d60 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
37d70 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
37d80 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
37d90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
37da0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
37db0 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
37dc0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
37dd0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
37de0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
37df0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
37e00 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
37e10 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
37e20 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
37e30 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
37e40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
37e50 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
37e60 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
37e70 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
37e80 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
37e90 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
37ea0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
37eb0 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
37ec0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
37ed0 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
37ee0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
37ef0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
37f00 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
37f10 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
37f20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
37f30 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
37f40 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
37f50 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
37f60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
37f70 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
37f80 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
37f90 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
37fa0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
37fb0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
37fc0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
37fd0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
37fe0 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
37ff0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
38000 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
38010 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
38020 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38030 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
38040 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
38050 20 43 61 63 68 65 0a 2a 2a 0a 2a 2a 20 5e 28 54   Cache.**.** ^(T
38060 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  his routine enab
38070 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
38080 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74  the sharing of t
38090 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68  he database cach
380a0 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20  e.** and schema 
380b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
380c0 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73  between [databas
380d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63  e connection | c
380e0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74  onnections].** t
380f0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
38100 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20  ase. Sharing is 
38110 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61  enabled if the a
38120 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a  rgument is true.
38130 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ** and disabled 
38140 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  if the argument 
38150 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a  is false.)^.**.*
38160 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67  * ^Cache sharing
38170 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20   is enabled and 
38180 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20  disabled for an 
38190 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a  entire process..
381a0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61  ** This is a cha
381b0 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65  nge as of SQLite
381c0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20   version 3.5.0. 
381d0 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e  In prior version
381e0 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20  s of SQLite,.** 
381f0 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62  sharing was enab
38200 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20  led or disabled 
38210 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20  for each thread 
38220 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
38230 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68  * ^(The cache sh
38240 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62  aring mode set b
38250 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  y this interface
38260 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62   effects all sub
38270 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
38280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
38290 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
382a0 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b  pen_v2()], and [
382b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
382c0 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64  ]..** Existing d
382d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
382e0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65  ons continue use
382f0 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64   the sharing mod
38300 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e  e.** that was in
38310 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74   effect at the t
38320 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70  ime they were op
38330 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ened.)^.**.** ^(
38340 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
38350 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
38360 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65   if shared cache
38370 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20   was enabled or 
38380 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63  disabled.** succ
38390 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65  essfully.  An [e
383a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
383b0 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65  turned otherwise
383c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65  .)^.**.** ^Share
383d0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
383e0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
383f0 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
38400 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
38410 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
38420 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
38430 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
38440 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
38450 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
38460 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
38470 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  citly..**.** Thi
38480 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  s interface is t
38490 68 72 65 61 64 73 61 66 65 20 6f 6e 20 70 72 6f  hreadsafe on pro
384a0 63 65 73 73 6f 72 73 20 77 68 65 72 65 20 77 72  cessors where wr
384b0 69 74 69 6e 67 20 61 0a 2a 2a 20 33 32 2d 62 69  iting a.** 32-bi
384c0 74 20 69 6e 74 65 67 65 72 20 69 73 20 61 74 6f  t integer is ato
384d0 6d 69 63 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  mic..**.** See A
384e0 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
384f0 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
38500 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
38510 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
38520 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
38530 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
38540 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
38550 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
38560 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
38570 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
38580 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
38590 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
385a0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
385b0 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
385c0 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
385d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
385e0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
385f0 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
38600 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
38610 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
38620 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
38630 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
38640 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
38650 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
38660 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
38670 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
38680 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
38690 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
386a0 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
386b0 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
386c0 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
386d0 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
386e0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
386f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
38700 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
38710 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
38720 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
38730 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
38740 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
38750 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
38760 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
38770 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  T]..**.** See al
38780 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  so: [sqlite3_db_
38790 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
387a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
387b0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
387c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
387d0 49 33 52 45 46 3a 20 46 72 65 65 20 4d 65 6d 6f  I3REF: Free Memo
387e0 72 79 20 55 73 65 64 20 42 79 20 41 20 44 61 74  ry Used By A Dat
387f0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
38800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
38810 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d  te3_db_release_m
38820 65 6d 6f 72 79 28 44 29 20 69 6e 74 65 72 66 61  emory(D) interfa
38830 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
38840 72 65 65 20 61 73 20 6d 75 63 68 20 68 65 61 70  ree as much heap
38850 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 73 20 70 6f  .** memory as po
38860 73 73 69 62 6c 65 20 66 72 6f 6d 20 64 61 74 61  ssible from data
38870 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
38880 44 2e 20 55 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a  D. Unlike the.**
38890 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 7