/ Hex Artifact Content
Login

Artifact 50e7c597334f704c1a5f76818dbee01ef9880a2b:


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 23 69 66 6e 64 65 66  RIMENTAL.#ifndef
09c0: 20 5f 5f 4f 53 58 5f 41 56 41 49 4c 41 42 4c 45   __OSX_AVAILABLE
09d0: 5f 42 55 54 5f 44 45 50 52 45 43 41 54 45 44 0a  _BUT_DEPRECATED.
09e0: 23 64 65 66 69 6e 65 20 5f 5f 4f 53 58 5f 41 56  #define __OSX_AV
09f0: 41 49 4c 41 42 4c 45 5f 42 55 54 5f 44 45 50 52  AILABLE_BUT_DEPR
0a00: 45 43 41 54 45 44 28 4d 61 63 4f 53 41 76 61 69  ECATED(MacOSAvai
0a10: 6c 61 62 6c 65 2c 20 4d 61 63 4f 53 44 65 70 72  lable, MacOSDepr
0a20: 65 63 61 74 65 64 2c 20 69 50 68 6f 6e 65 4f 53  ecated, iPhoneOS
0a30: 41 76 61 69 6c 61 62 6c 65 2c 20 69 50 68 6f 6e  Available, iPhon
0a40: 65 4f 53 44 65 70 72 65 63 61 74 65 64 29 0a 23  eOSDeprecated).#
0a50: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  endif../*.** Ens
0a60: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0a70: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0a80: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0a90: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0aa0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0ab0: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0ac0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0ad0: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ae0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0af0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0b00: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0b10: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0b20: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0b30: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0b40: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0b50: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0b60: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0b70: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0b80: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0b90: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0ba0: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0bb0: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0bc0: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0bd0: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0be0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0bf0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0c00: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0c10: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0c20: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0c30: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0c40: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0c50: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0c60: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0c70: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0c80: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0ca0: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0cb0: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0cc0: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0cd0: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0ce0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0cf0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0d00: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0d10: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0d20: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0d30: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0d40: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0d50: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0d60: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0d70: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0d80: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0d90: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0da0: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0db0: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0dc0: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0dd0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0de0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0df0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0e00: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0e10: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0e20: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0e30: 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38  e version 3.6.18
0e40: 2c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  , SQLite source 
0e50: 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74  code has been st
0e60: 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c  ored in the.** <
0e70: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77  a href="http://w
0e80: 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72  ww.fossil-scm.or
0e90: 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69  g/">Fossil confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61  ent.** system</a
0ec0: 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  >.  ^The SQLITE_
0ed0: 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20  SOURCE_ID macro 
0ee0: 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20  evaluates to.** 
0ef0: 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
0f00: 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74  dentifies a part
0f10: 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20  icular check-in 
0f20: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74  of SQLite.** wit
0f30: 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72  hin its configur
0f40: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
0f50: 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53   system.  ^The S
0f60: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a  QLITE_SOURCE_ID.
0f70: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
0f80: 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20  ns the date and 
0f90: 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63  time of the chec
0fa0: 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61  k-in (UTC) and a
0fb0: 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f  n SHA1.** hash o
0fc0: 66 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75  f the entire sou
0fd0: 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20  rce tree..**.** 
0fe0: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
0ff0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d  e3_libversion()]
1000: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69  ,.** [sqlite3_li
1010: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1020: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75  )], [sqlite3_sou
1030: 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  rceid()],.** [sq
1040: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
1050: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
1060: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65  ce_id()]..*/.#de
1070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1080: 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45  ION        "--VE
1090: 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51  RS--".#define SQ
10a0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
10b0: 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55  BER --VERSION-NU
10c0: 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53  MBER--.#define S
10d0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
10e0: 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49       "--SOURCE-I
10f0: 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  D--"../*.** CAPI
1100: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1110: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
1120: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  umbers.** KEYWOR
1130: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
1140: 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75  ion, sqlite3_sou
1150: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
1160: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
1170: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
1180: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
1190: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
11a0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
11b0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
11c0: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
11d0: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
11e0: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
11f0: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1200: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1210: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1220: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1230: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1240: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
1250: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
1260: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1270: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
1280: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
1290: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
12a0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
12b0: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
12c0: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
12d0: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
12e0: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
12f0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1300: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1310: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1320: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1330: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1340: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1350: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
1360: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1370: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
1380: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
1390: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
13a0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
13b0: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
13c0: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
13d0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
13e0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
13f0: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1400: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1410: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1420: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1430: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1440: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
1450: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
1460: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
1470: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
1480: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
1490: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
14a0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
14b0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
14c0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
14d0: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
14e0: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
14f0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1500: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1510: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1520: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1530: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1540: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
1550: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
1560: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
1570: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
1580: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
1590: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
15a0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
15b0: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
15c0: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
15d0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
15e0: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
15f0: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1600: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1610: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
1620: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
1630: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
1640: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
1650: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
1660: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1670: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1680: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
1690: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
16a0: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
16b0: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
16c0: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  */.SQLITE_EXTERN
16d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16e0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63  te3_version[];.c
16f0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1700: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
1710: 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  id);.const char 
1720: 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  *sqlite3_sourcei
1730: 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  d(void);.int sql
1740: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1750: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1760: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1770: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1780: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1790: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
17a0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
17b0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17c0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17d0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17e0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17f0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
1800: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
1810: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1820: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1830: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1840: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1850: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1860: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1880: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1890: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
18a0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
18b0: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18c0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18d0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18e0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18f0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
1900: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
1910: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1920: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1930: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1940: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1950: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1960: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1970: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1980: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1990: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
19a0: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
19b0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19c0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19d0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19e0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19f0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
1a00: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
1a10: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a20: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a30: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a40: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a50: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a60: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a70: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a80: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a90: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1aa0: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1ab0: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1ac0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ad0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ae0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1af0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1b00: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b20: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b30: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b40: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b50: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b60: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b70: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d  .int sqlite3_com
1b80: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1b90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74  const char *zOpt
1ba0: 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61  Name);.const cha
1bb0: 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  r *sqlite3_compi
1bc0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74  leoption_get(int
1bd0: 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a   N);.#endif../*.
1be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
1bf0: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20  t To See If The 
1c00: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61  Library Is Threa
1c10: 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dsafe.**.** ^The
1c20: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1c30: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  afe() function r
1c40: 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61  eturns zero if a
1c50: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51  nd only if.** SQ
1c60: 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65  Lite was compile
1c70: 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20  d with mutexing 
1c80: 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65  code omitted due
1c90: 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   to the.** [SQLI
1ca0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63  TE_THREADSAFE] c
1cb0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
1cc0: 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20  on being set to 
1cd0: 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0..**.** SQLite 
1ce0: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
1cf0: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20  with or without 
1d00: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a  mutexes.  When.*
1d10: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
1d20: 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70  READSAFE] C prep
1d30: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69  rocessor macro i
1d40: 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65  s 1 or 2, mutexe
1d50: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
1d60: 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74   and SQLite is t
1d70: 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e  hreadsafe.  When
1d80: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1d90: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
1da0: 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20  o is 0, .** the 
1db0: 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74  mutexes are omit
1dc0: 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68  ted.  Without th
1dd0: 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73  e mutexes, it is
1de0: 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20   not safe.** to 
1df0: 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75  use SQLite concu
1e00: 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72  rrently from mor
1e10: 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61  e than one threa
1e20: 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e  d..**.** Enablin
1e30: 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73  g mutexes incurs
1e40: 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65   a measurable pe
1e50: 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74  rformance penalt
1e60: 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  y..** So if spee
1e70: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
1e80: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
1e90: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
1ea0: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
1eb0: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
1ec0: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
1ed0: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
1ee0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65  enabled..** ^The
1ef0: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1f00: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1f10: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
1f20: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
1f30: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
1f40: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
1f50: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
1f60: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
1f70: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1f80: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1f90: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1fa0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1fb0: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1fc0: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1fd0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1fe0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
1ff0: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
2000: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
2010: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
2020: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
2030: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
2040: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
2050: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
2060: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
2070: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f  E_THREADSAFE=1 o
2080: 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65  r =2 then mutexe
2090: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
20a0: 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20   default but.** 
20b0: 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20  can be fully or 
20c0: 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c  partially disabl
20d0: 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20  ed using a call 
20e0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
20f0: 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68  ig()].** with th
2100: 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f  e verbs [SQLITE_
2110: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
2120: 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EAD], [SQLITE_CO
2130: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
2140: 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
2150: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20  _CONFIG_MUTEX]. 
2160: 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61   ^(The return va
2170: 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71  lue of the.** sq
2180: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
2190: 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77  () function show
21a0: 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69  s only the compi
21b0: 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20  le-time setting 
21c0: 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66  of.** thread saf
21d0: 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e  ety, not any run
21e0: 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f  -time changes to
21f0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61   that setting ma
2200: 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33  de by.** sqlite3
2210: 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74  _config(). In ot
2220: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72  her words, the r
2230: 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
2240: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2250: 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68  afe().** is unch
2260: 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74  anged by calls t
2270: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
2280: 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ().)^.**.** See 
2290: 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
22a0: 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ode] documentati
22b0: 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
22c0: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
22d0: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  /.int sqlite3_th
22e0: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
22f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2300: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2310: 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b  tion Handle.** K
2320: 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61  EYWORDS: {databa
2330: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b  se connection} {
2340: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2350: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68  ions}.**.** Each
2360: 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74   open SQLite dat
2370: 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65  abase is represe
2380: 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65  nted by a pointe
2390: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
23a0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75   of.** the opaqu
23b0: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
23c0: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
23d0: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
23e0: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
23f0: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
2400: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
2410: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2420: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
2430: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
2440: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2450: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
2460: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
2470: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  , and [sqlite3_c
2480: 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  lose()].** and [
2490: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
24a0: 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74  ()] are its dest
24b0: 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20  ructors.  There 
24c0: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a  are many other.*
24d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  * interfaces (su
24e0: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
24f0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2500: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2510: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2530: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2540: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2550: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
2560: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
2570: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
2580: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2590: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
25b0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
25c0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
25d0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
25e0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
25f0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2600: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2610: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2620: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2630: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2640: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2650: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2660: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2670: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2680: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2690: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
26a0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
26b0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
26c0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
26d0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
26e0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
26f0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2700: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2710: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2720: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2730: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2740: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2750: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2760: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2770: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
2780: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
2790: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
27a0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
27b0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
27c0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
27d0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
27e0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
27f0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2800: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2810: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2820: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2830: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2850: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
2860: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
2870: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2880: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
2890: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
28a0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
28b0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
28c0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
28d0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
28e0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
28f0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2900: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2910: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2920: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2930: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2940: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2950: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2960: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
2970: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
2980: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
2990: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
29a0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
29b0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
29c0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
29d0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
29e0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
29f0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2a00: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2a10: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2a20: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2a30: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2a40: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2a50: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
2a60: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
2a70: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
2a80: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
2a90: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2aa0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
2ab0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2ac0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ad0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ae0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2af0: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2b00: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66  destructors.** f
2b10: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
2b20: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c   object..** ^Cal
2b30: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c  ls to sqlite3_cl
2b40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2b50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74  3_close_v2() ret
2b60: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2b70: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
2b80: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
2b90: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ba0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2bb0: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
2bc0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
2bd0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
2be0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2bf0: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
2c00: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
2c10: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
2c20: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
2c30: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2c40: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
2c50: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
2c60: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
2c70: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
2c80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
2c90: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
2ca0: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
2cb0: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
2cc0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
2cd0: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
2ce0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf0: 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e  nts.** and unfin
2d00: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2d10: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
2d20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d30: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
2d40: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
2d50: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
2d60: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
2d70: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
2d80: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
2d90: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2da0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
2db0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
2dc0: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
2dd0: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
2de0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2df0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
2e00: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
2e10: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
2e20: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
2e30: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
2e40: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
2e50: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
2e60: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
2e70: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
2e80: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
2e90: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2ea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2eb0: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
2ec0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
2ed0: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
2ee0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2ef0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2f00: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
2f10: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
2f20: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
2f30: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
2f40: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
2f50: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
2f60: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
2f70: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
2f80: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
2f90: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
2fa0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
2fb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2fc0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2fd0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fe0: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2ff0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
3000: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
3010: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3020: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
3030: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
3040: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
3050: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
3060: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
3070: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
3080: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
3090: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
30a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
30c0: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
30d0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
30e0: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
30f0: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
3100: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
3110: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
3120: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
3130: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
3140: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
3150: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
3160: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
3170: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
3180: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
3190: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
31a0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
31b0: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
31c0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
31d0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
31e0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
31f0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
3200: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3210: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
3220: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
3230: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
3240: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
3250: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
3260: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
3270: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
3280: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
3290: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
32a0: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
32b0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
32c0: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
32d0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32e0: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
32f0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  ;.int sqlite3_cl
3300: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
3310: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
3320: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
3330: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
3340: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
3350: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
3360: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
3370: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
3380: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
3390: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
33a0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
33b0: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
33c0: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
33d0: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
33e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f0: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
3400: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
3410: 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rface.**.** The 
3420: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3430: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3440: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
3450: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
3460: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
3470: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
3480: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3490: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34a0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
34b0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
34c0: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
34d0: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
34e0: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
34f0: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3500: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3520: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3530: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3540: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
3550: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
3560: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
3570: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3580: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3590: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35a0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
35b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35c0: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
35d0: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
35e0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
35f0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3600: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3610: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3620: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3630: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3640: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
3650: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
3660: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
3670: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
3680: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3690: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36a0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
36b0: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
36c0: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
36d0: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
36e0: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
36f0: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3700: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3710: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3720: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3730: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3740: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
3750: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
3760: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
3770: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
3780: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3790: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37a0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
37b0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
37c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
37d0: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
37e0: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
37f0: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3800: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3810: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3820: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3840: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3850: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
3860: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
3870: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
3880: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3890: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38a0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
38b0: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
38c0: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
38d0: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
38e0: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
38f0: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3900: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3910: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3920: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3930: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3940: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3950: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3960: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
3970: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
3980: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
3990: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39a0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
39b0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
39c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
39e0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
39f0: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a00: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a10: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a20: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a30: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a40: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3a50: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3a60: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3a70: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3a80: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3aa0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3ab0: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3ac0: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3ad0: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3ae0: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3af0: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b00: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b10: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b20: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b30: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b40: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3b50: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3b60: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3b70: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3b80: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3b90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3ba0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3bb0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3bc0: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3bd0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3be0: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3bf0: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c00: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c10: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c20: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c30: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c40: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3c50: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3c60: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3c70: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3c80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3c90: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3ca0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3cb0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3cc0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3cd0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3ce0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3cf0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d00: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d10: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d20: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d30: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d40: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3d50: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3d60: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3d70: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3d80: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3d90: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3da0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3db0: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3dc0: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3dd0: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3de0: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3df0: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e00: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e10: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e20: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e30: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e40: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3e50: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3e60: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3e70: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3e80: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3e90: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ea0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
3eb0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ec0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ed0: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3ee0: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3ef0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f00: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f20: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f40: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3f50: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3f60: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f70: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3f80: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3f90: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3fa0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3fb0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3fc0: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
3fd0: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
3fe0: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
3ff0: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4000: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4010: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4020: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4030: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4040: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
4050: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
4060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4080: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
4090: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40a0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
40d0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
40e0: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
40f0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4100: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4110: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4120: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4150: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
4160: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
4170: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41a0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
41b0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
41c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
41d0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
41e0: 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
41f0: 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20  OK {error code} 
4200: 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a  {error codes}.**
4210: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
4220: 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74  lt code} {result
4230: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61   codes}.**.** Ma
4240: 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69  ny SQLite functi
4250: 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e  ons return an in
4260: 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64  teger result cod
4270: 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73  e from the set s
4280: 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20  hown.** here in 
4290: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74  order to indicat
42a0: 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
42b0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
42c0: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
42d0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
42e0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
42f0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
4300: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
4310: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
4320: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4330: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
4340: 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
4350: 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  ()] [SQLITE_ROLL
4360: 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  BACK | result co
4370: 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  des]..*/.#define
4380: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4390: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
43a0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
43b0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
43c0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
43d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
43e0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
43f0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4400: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4430: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4440: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4450: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4460: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4470: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4480: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4490: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
44a0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
44b0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
44c0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
44d0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
44e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44f0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4500: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4510: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4520: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4530: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4540: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4550: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4560: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4570: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4580: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4590: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
45a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
45b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
45c0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
45d0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
45e0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
45f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4600: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4610: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4620: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4630: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4650: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4660: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4670: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4680: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4690: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
46a0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
46b0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
46c0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
46d0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
46e0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
46f0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4700: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4710: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4720: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4730: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4740: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4750: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4760: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4770: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4780: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4790: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
47a0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
47b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
47d0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
47e0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
47f0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4810: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4820: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4830: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4840: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4850: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4860: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4870: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4880: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4890: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
48a0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
48b0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
48c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48d0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
48e0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
48f0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4900: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4910: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4920: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4930: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4940: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4950: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4960: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4970: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4990: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
49a0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
49b0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
49c0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
49d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
49e0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
49f0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4a00: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4a10: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4a20: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4a30: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4a40: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4a60: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4a70: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4a80: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4a90: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4aa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4ab0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4ac0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4ad0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ae0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4b00: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4b10: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4b20: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4b30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4b40: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4b50: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4b60: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4b70: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4b80: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4b90: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4ba0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4bb0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4bc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4bd0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4be0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4bf0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4c00: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4c10: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4c20: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4c30: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4c40: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4c50: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4c60: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
4c70: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4c80: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
4c90: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
4cb0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4cc0: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4cd0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4ce0: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4cf0: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4d00: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4d10: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4d20: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4d30: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4d40: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4d50: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
4d60: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
4d70: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
4d80: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
4d90: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
4da0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
4db0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4dc0: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4dd0: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4de0: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4df0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4e00: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4e10: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4e20: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4e30: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4e40: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4e50: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4e60: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4e70: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4e80: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4e90: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4ea0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
4eb0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4ec0: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4ed0: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4ee0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4ef0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4f00: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4f10: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4f20: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4f30: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4f40: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4f50: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4f60: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
4f70: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
4f80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
4f90: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4fa0: 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 72 65 61  odes will increa
4fb0: 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  se.** over time.
4fc0: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
4fd0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
4fe0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
4ff0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
5000: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
5010: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
5020: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
5030: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
5040: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
5050: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
5060: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
5070: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
5080: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
5090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50a0: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
50b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50c0: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
50d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50e0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
50f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5100: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5120: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5140: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
5150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5160: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
5170: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5180: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
5190: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51a0: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
51b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51c0: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
51d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51e0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
51f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5200: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5210: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5220: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
5230: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5240: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5250: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
5260: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
5270: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5280: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
52a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
52b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52c0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
52d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
52e0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
52f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5300: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
5310: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
5320: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
5330: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5340: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
5350: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
5360: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
5370: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5380: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
5390: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
53a0: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
53b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
53c0: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
53e0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
5410: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
5420: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
5430: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5440: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
5450: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
5460: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
5470: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5480: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
5490: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
54a0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
54b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
54c0: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
54d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
54e0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
54f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5500: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
5510: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5520: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
5530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5540: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
5550: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
5560: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
5570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5580: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
5590: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
55a0: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
55b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
55c0: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
55d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
55e0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
55f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5600: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
5610: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
5620: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
5630: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5640: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
5650: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41  SQLITE_IOERR_MMA
5660: 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  P              (
5670: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5680: 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  24<<8)).#define 
5690: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54  SQLITE_IOERR_GET
56a0: 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28  TEMPPATH       (
56b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
56c0: 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  25<<8)).#define 
56d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e  SQLITE_IOERR_CON
56e0: 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28  VPATH          (
56f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5700: 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  26<<8)).#define 
5710: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
5720: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
5730: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
5740: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5750: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
5760: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
5770: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
5780: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5790: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e  e SQLITE_BUSY_SN
57a0: 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20  APSHOT          
57b0: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
57c0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69  |  (2<<8)).#defi
57d0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57e0: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
57f0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5800: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  EN | (1<<8)).#de
5810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5820: 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20  OPEN_ISDIR      
5830: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5840: 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OPEN | (2<<8)).#
5850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5860: 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20  NTOPEN_FULLPATH 
5870: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5880: 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29  NTOPEN | (3<<8))
5890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58a0: 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54  CANTOPEN_CONVPAT
58b0: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
58c0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38  CANTOPEN | (4<<8
58d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58e0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
58f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5900: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
5910: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5920: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
5930: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5940: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5950: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5970: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5980: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5990: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
59a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
59b0: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28  ROLLBACK       (
59c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59d0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
59e0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59f0: 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20  Y_DBMOVED       
5a00: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5a10: 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  Y | (4<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
5a30: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5a50: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5a60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a70: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5a80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a90: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5ac0: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5b00: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5bd0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5c10: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d20: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
5d30: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
5d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d50: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d60: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
5d70: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
5d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d90: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
5da0: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
5db0: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
5dc0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
5dd0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
5de0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
5df0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
5e00: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
5e10: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
5e20: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
5e30: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e50: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
5e60: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
5e70: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5e80: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
5e90: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
5ea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5eb0: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5ec0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
5ed0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5ee0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5ef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f00: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
5f10: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
5f20: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f30: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f50: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
5f60: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5f70: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f80: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5fa0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5fb0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
5fc0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5fe0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5ff0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6000: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6020: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
6030: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
6040: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6060: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6070: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6080: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6090: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
60a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
60b0: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
60c0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
60d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
60e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
60f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6100: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
6110: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
6120: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
6150: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
6160: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6180: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6190: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
61a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
61b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61c0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
61d0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
61e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
61f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6200: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
6210: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
6220: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6240: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
6250: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
6260: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6280: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6290: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
62a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62c0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
62d0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
62e0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
62f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6310: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
6320: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
6330: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6340: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6360: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6370: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6380: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6390: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
63a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63b0: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
63c0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
63d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
63e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
63f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6400: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
6410: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
6420: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6440: 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54 49 4f  EN_FILEPROTECTIO
6450: 4e 5f 43 4f 4d 50 4c 45 54 45 20 20 20 20 20 20  N_COMPLETE      
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6470: 20 20 20 20 20 20 20 30 78 30 30 31 30 30 30 30         0x0010000
6480: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6490: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43  _OPEN_FILEPROTEC
64a0: 54 49 4f 4e 5f 43 4f 4d 50 4c 45 54 45 55 4e 4c  TION_COMPLETEUNL
64b0: 45 53 53 4f 50 45 4e 20 20 20 20 20 20 20 20 20  ESSOPEN         
64c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 32 30            0x0020
64d0: 30 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0000.#define SQL
64e0: 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f  ITE_OPEN_FILEPRO
64f0: 54 45 43 54 49 4f 4e 5f 43 4f 4d 50 4c 45 54 45  TECTION_COMPLETE
6500: 55 4e 54 49 4c 46 49 52 53 54 55 53 45 52 41 55  UNTILFIRSTUSERAU
6510: 54 48 45 4e 54 49 43 41 54 49 4f 4e 20 30 78 30  THENTICATION 0x0
6520: 30 33 30 30 30 30 30 0a 23 64 65 66 69 6e 65 20  0300000.#define 
6530: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45  SQLITE_OPEN_FILE
6540: 50 52 4f 54 45 43 54 49 4f 4e 5f 4e 4f 4e 45 20  PROTECTION_NONE 
6550: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6560: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6570: 30 78 30 30 34 30 30 30 30 30 0a 23 64 65 66 69  0x00400000.#defi
6580: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6590: 49 4c 45 50 52 4f 54 45 43 54 49 4f 4e 5f 4d 41  ILEPROTECTION_MA
65a0: 53 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SK              
65b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65c0: 20 20 20 30 78 30 30 37 30 30 30 30 30 0a 0a 2f     0x00700000../
65d0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
65e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
65f0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6600: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6610: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
6620: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
6630: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
6640: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
6650: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
6660: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6670: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6680: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6690: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
66a0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
66b0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
66c0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
66d0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
66e0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
66f0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6700: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6710: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6720: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
6730: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6740: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6750: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6760: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6770: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6780: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6790: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
67a0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
67b0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
67c0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
67d0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
67e0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
67f0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6800: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6810: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6820: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6830: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6840: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6850: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6860: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6870: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6880: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6890: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
68a0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
68b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
68c0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
68d0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
68e0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
68f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6900: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6910: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6920: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6930: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6940: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6950: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6960: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
6970: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6980: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6990: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
69a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
69b0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
69c0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
69d0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
69e0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
69f0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6a00: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6a10: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
6a20: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
6a30: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
6a40: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
6a50: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
6a60: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
6a70: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6a80: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6a90: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6aa0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6ab0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6ac0: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6ad0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6ae0: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6af0: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6b00: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6b10: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6b20: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6b30: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6b40: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6b50: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6b60: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6b70: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6b80: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ba0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6bc0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6bd0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6be0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6bf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c10: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6c30: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6c40: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6c50: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6c60: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c80: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6c90: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6ca0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6cb0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6cc0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6cd0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cf0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6d00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6d10: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6d20: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6d30: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6d40: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6d50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6d60: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6d70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6d80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d90: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6da0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6db0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6dc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6dd0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6de0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e00: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6e10: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6e20: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6e30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6e40: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6e50: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6e70: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6e80: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6e90: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6ea0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6eb0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6ec0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6ed0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6ee0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6ef0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6f00: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6f10: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6f20: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6f30: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6f40: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6f50: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6f60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6f70: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6f80: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6f90: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6fa0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6fb0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6fc0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6fe0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6ff0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
7000: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
7010: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
7020: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
7030: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
7040: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
7050: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
7060: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
7070: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
7080: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7090: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
70a0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
70b0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
70c0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
70d0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
70e0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
70f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7100: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7110: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7120: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7130: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7140: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7150: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7160: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7170: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
7180: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
7190: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
71a0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
71b0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
71c0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
71d0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
71e0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
71f0: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7200: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7210: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7220: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7230: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7240: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7250: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7260: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7270: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
7280: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7290: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
72a0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
72b0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
72c0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
72d0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
72e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
72f0: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7300: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7310: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7320: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7330: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7340: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7350: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7360: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7370: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
7380: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
7390: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
73a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
73b0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
73c0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
73d0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
73e0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
73f0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7400: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7410: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7420: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7430: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7440: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7450: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7460: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7470: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
7480: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
7490: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
74a0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
74b0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
74c0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
74d0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
74e0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
74f0: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7500: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7510: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7520: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7530: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7540: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7550: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7560: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
7580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7590: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
75a0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
75b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
75c0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
75d0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
75e0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
75f0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7600: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7610: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7620: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7630: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7640: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7650: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7660: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7670: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
7680: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
7690: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
76a0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
76b0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
76c0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
76d0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
76e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
76f0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7700: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7710: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7720: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7730: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7740: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7750: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7760: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7770: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
7780: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7790: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
77a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
77b0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
77c0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
77d0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
77e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
77f0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7800: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7810: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7820: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7830: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7860: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7870: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7880: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
7890: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
78a0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
78b0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
78c0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
78d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
78e0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
78f0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7900: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7910: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7920: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7930: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7940: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7950: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7960: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7970: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7980: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7990: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
79a0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
79b0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
79c0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
79d0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
79e0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
79f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7a00: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7a10: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7a20: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7a30: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7a40: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7a50: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7a60: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7a70: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7a80: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
7a90: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
7aa0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7ab0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7ac0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7ad0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7ae0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7af0: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7b00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7b10: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7b20: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7b30: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7b40: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7b50: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7b60: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7b70: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7b80: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7b90: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ba0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7bb0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7bc0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7bd0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7be0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7bf0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7c00: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7c10: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7c20: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7c30: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7c40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7c50: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7c60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7c70: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7c80: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7ca0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7cb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7cc0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7cd0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ce0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7cf0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7d00: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7d10: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7d20: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7d30: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7d40: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7d50: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7d60: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7d70: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7d80: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7d90: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7da0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7db0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7dc0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7dd0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7de0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7df0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7e00: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7e10: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7e20: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7e30: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7e40: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7e50: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7e60: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7e70: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7e80: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7e90: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7ea0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7eb0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7ec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7ed0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7ee0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7ef0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7f00: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7f20: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7f30: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7f40: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7f50: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7f60: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7f70: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7f80: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7f90: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7fa0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7fb0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7fc0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7fd0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7fe0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7ff0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
8000: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
8010: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
8020: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
8030: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
8040: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
8050: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
8060: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
8070: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
8080: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
8090: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
80a0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
80b0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
80c0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
80d0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
80e0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
80f0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8100: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8110: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
8130: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
8140: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
8150: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
8160: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
8170: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
8180: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
8190: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
81a0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
81b0: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
81c0: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
81d0: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
81e0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
81f0: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
8200: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
8210: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
8220: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
8230: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
8240: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
8250: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
8260: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
8270: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
8280: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
8290: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
82a0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
82b0: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
82c0: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
82d0: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
82e0: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
82f0: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
8300: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
8310: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
8320: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8330: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
8340: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
8350: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
8360: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
8370: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
8380: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
8390: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
83a0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
83b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
83d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
83f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8400: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
8410: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
8430: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8440: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
8450: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8460: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
8470: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8480: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
8490: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
84a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
84b0: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
84c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
84d0: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
84e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
84f0: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
8500: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
8510: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8520: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8530: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
8540: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
8550: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8560: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8570: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
8580: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
8590: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
85a0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
85b0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
85c0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
85d0: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
85e0: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
85f0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
8600: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
8610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
8620: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
8630: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
8640: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
8650: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
8660: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
8670: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
8680: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
8690: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
86a0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
86b0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
86c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
86d0: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
86e0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
86f0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
8700: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
8710: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
8720: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
8730: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
8740: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
8750: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
8760: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
8770: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
8780: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
8790: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
87a0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
87b0: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
87c0: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
87d0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
87e0: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
87f0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
8800: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
8810: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8820: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
8830: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
8840: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
8850: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
8860: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
8870: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
8880: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
8890: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
88a0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
88b0: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
88c0: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
88d0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
88e0: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
88f0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
8900: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
8910: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8920: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
8930: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8940: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
8950: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8960: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8970: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
8980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8990: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
89a0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
89b0: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
89c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
89d0: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
89e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
89f0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
8a00: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
8a10: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8a20: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8a30: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
8a40: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
8a60: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
8a70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8a90: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8ab0: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
8ac0: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
8ad0: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
8ae0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8af0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
8b00: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
8b10: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
8b20: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8b30: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b40: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
8b50: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
8b60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
8b70: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
8b80: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
8b90: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
8ba0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8bb0: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
8bc0: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
8bd0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
8be0: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
8bf0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8c00: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
8c10: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
8c20: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
8c30: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8c40: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8c50: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 2 */.  int (
8c60: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33  *xFetch)(sqlite3
8c70: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8c80: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74  int64 iOfst, int
8c90: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70   iAmt, void **pp
8ca0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65  );.  int (*xUnfe
8cb0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8cc0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8cd0: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70  4 iOfst, void *p
8ce0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8cf0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8d00: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f  for version 3 */
8d10: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
8d20: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
8d30: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
8d40: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
8d50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8d60: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
8d70: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
8d80: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
8d90: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
8da0: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
8db0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8dc0: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
8dd0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8de0: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
8df0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
8e00: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
8e10: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
8e20: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8e30: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8e40: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8e50: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8e60: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8e70: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8e80: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8e90: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8ea0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8eb0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8ec0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ed0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8ee0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8ef0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8f00: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f10: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8f20: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8f30: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8f40: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8f50: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8f60: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8f70: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8f80: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8f90: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
8fa0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
8fb0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
8fc0: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
8fd0: 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ned..** <ul>.** 
8fe0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8ff0: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
9000: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9010: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
9020: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
9030: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
9040: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
9050: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
9060: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
9070: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
9080: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
9090: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
90a0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
90b0: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
90c0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
90d0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
90e0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
90f0: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
9100: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
9110: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
9120: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9130: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
9140: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
9150: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
9160: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
9170: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
9180: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
9190: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
91a0: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
91b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
91c0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
91d0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
91e0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
91f0: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
9200: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
9210: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9220: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
9230: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
9240: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
9250: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
9260: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
9270: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
9280: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
9290: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
92a0: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
92b0: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
92c0: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
92d0: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
92e0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
92f0: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
9300: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
9310: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
9320: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
9330: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
9340: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
9350: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
9360: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
9370: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
9380: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
9390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
93a0: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
93b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93c0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
93d0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
93e0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
93f0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
9400: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
9410: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
9420: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9430: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9440: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
9450: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9460: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
9470: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
9480: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
9490: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
94a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
94b0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
94c0: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65  No longer in use
94d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
94e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
94f0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
9500: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63  _FCNTL_SYNC] opc
9510: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
9520: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
9530: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e  QLite and.** sen
9540: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d  t to the VFS imm
9550: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
9560: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
9570: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
9580: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
9590: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72  e descriptor. Or
95a0: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d  , if the xSync m
95b0: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76  ethod is not inv
95c0: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65  oked .** because
95d0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f   the user has co
95e0: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20  nfigured SQLite 
95f0: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  with .** [PRAGMA
9600: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
9610: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9620: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76  s=OFF] it is inv
9630: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a  oked in place .*
9640: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d  * of the xSync m
9650: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63  ethod. In most c
9660: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65  ases, the pointe
9670: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  r argument passe
9680: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66  d with.** this f
9690: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e  ile-control is N
96a0: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  ULL. However, if
96b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
96c0: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63  le is being sync
96d0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
96e0: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73   a multi-databas
96f0: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72  e commit, the ar
9700: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
9710: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
9720: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  d.** string cont
9730: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73  aining the trans
9740: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a  actions master-j
9750: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65  ournal file name
9760: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a  . VFSes that .**
9770: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9780: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20  s signal should 
9790: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
97a0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
97b0: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68  lications .** sh
97c0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
97d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97e0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
97f0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
9800: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72   so may .** disr
9810: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
9820: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9830: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9840: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9850: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9860: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9870: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54  _PHASETWO]].** T
9880: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9890: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
98a0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
98b0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
98c0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
98d0: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  d sent to the VF
98e0: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61  S after a transa
98f0: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63  ction has been c
9900: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61  ommitted immedia
9910: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f  tely.** but befo
9920: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  re the database 
9930: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53  is unlocked. VFS
9940: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e  es that do not n
9950: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a  eed this signal.
9960: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  ** should silent
9970: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9980: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9990: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
99a0: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
99b0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
99c0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
99d0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
99e0: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a   disrupt the .**
99f0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9a00: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9a10: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
9a20: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9a30: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9a40: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9a50: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
9a60: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9a70: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
9a80: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
9a90: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
9aa0: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
9ab0: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
9ac0: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
9ad0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
9ae0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
9af0: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
9b00: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
9b10: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
9b20: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
9b30: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
9b40: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
9b50: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
9b60: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
9b70: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
9b80: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
9b90: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
9ba0: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
9bb0: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
9bc0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9bd0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
9be0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
9bf0: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
9c00: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
9c10: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
9c20: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
9c30: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
9c40: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
9c50: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
9c60: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
9c70: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
9c80: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
9c90: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
9ca0: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
9cb0: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
9cc0: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
9cd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
9ce0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
9cf0: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
9d00: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
9d10: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
9d20: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
9d30: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
9d40: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
9d50: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
9d60: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
9d70: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
9d80: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
9d90: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
9da0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
9db0: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
9dc0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
9dd0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
9de0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
9df0: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
9e00: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
9e10: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
9e20: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
9e30: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
9e40: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
9e50: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
9e60: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
9e70: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
9e80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9e90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9ea0: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
9eb0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
9ec0: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
9ed0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
9ee0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
9ef0: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
9f00: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
9f10: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
9f20: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
9f30: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
9f40: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
9f50: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
9f60: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
9f70: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
9f80: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
9f90: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
9fa0: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
9fb0: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
9fc0: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
9fd0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
9fe0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
9ff0: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
a000: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
a010: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
a020: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
a030: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
a040: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
a050: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
a060: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
a070: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
a080: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
a090: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
a0a0: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
a0b0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
a0c0: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
a0d0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a0e0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
a0f0: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
a100: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
a110: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
a120: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a130: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a140: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a150: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a160: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a170: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a180: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a190: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a1a0: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
a1b0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
a1c0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
a1d0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
a1e0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a1f0: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a200: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a210: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a220: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
a230: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
a240: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a250: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a260: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a270: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a280: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
a290: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a2a0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
a2b0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
a2c0: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
a2d0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
a2e0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
a2f0: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
a300: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
a310: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
a320: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
a330: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
a340: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
a350: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
a360: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
a370: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
a380: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a390: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
a3a0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
a3b0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
a3c0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
a3d0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
a3e0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
a3f0: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
a400: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
a410: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
a420: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
a430: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
a440: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
a450: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
a460: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
a470: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
a480: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a490: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
a4a0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a4b0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a4c0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
a4d0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a4e0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
a4f0: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
a500: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
a510: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
a520: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
a530: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
a540: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
a550: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
a560: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
a570: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
a580: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
a590: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
a5a0: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
a5b0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
a5c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a5d0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
a5e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a5f0: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
a600: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
a610: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
a620: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
a630: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
a640: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
a650: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
a660: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
a670: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
a680: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
a690: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
a6a0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
a6b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
a6c0: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
a6d0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
a6e0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
a6f0: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
a700: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
a710: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a720: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
a730: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
a740: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
a750: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
a760: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
a770: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
a780: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
a790: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
a7a0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
a7b0: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
a7c0: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
a7d0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
a7e0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
a7f0: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
a800: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
a810: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
a820: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
a830: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
a840: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
a850: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
a860: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
a870: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
a880: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a8a0: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
a8b0: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
a8c0: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
a8d0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
a8e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
a8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
a900: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
a910: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a920: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
a930: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
a940: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
a950: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
a960: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
a970: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
a980: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
a990: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a9a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
a9b0: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
a9c0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
a9d0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
a9e0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
a9f0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
aa00: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
aa10: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
aa20: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
aa30: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
aa40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
aa50: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
aa60: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
aa70: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
aa80: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
aa90: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
aaa0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
aab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
aac0: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
aad0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
aae0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
aaf0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
ab00: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
ab10: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
ab20: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
ab30: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
ab40: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
ab50: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
ab60: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
ab70: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
ab80: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
ab90: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
aba0: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
abb0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
abc0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
abd0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
abe0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
abf0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
ac00: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
ac10: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
ac20: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ac30: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac40: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ac50: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ac60: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
ac70: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
ac80: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
ac90: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
aca0: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
acb0: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
acc0: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
acd0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20  ared statement. 
ace0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
acf0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ad00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
ad10: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
ad20: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
ad30: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
ad40: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
ad50: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
ad60: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
ad70: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
ad80: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
ad90: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
ada0: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
adb0: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
adc0: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
add0: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
ade0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
adf0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ae00: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
ae10: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
ae20: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ae30: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
ae40: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
ae50: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
ae60: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
ae70: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
ae80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ae90: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
aea0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
aeb0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
aec0: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
aed0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
aee0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
aef0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
af00: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
af10: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
af20: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
af30: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
af40: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
af50: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
af60: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
af70: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
af80: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
af90: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
afa0: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
afb0: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
afc0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
afd0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
afe0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
aff0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b000: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b010: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b020: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b030: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b040: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b050: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b060: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b070: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b080: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b090: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b0a0: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b0b0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b0c0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b0d0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b0e0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b0f0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b100: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b110: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b120: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b130: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b150: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b160: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b170: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b180: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b190: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b1a0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b1b0: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b1c0: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b1d0: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b1e0: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b1f0: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b200: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b210: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b220: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b230: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b240: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b250: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b260: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b270: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b280: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b290: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
b2a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
b2b0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
b2c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
b2d0: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
b2e0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
b2f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
b300: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
b310: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
b320: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
b330: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b340: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
b350: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b360: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
b370: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b380: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
b390: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
b3a0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
b3b0: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
b3c0: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
b3d0: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
b3e0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b3f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
b400: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
b410: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
b420: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
b430: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b440: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
b450: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
b460: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
b470: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
b480: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
b490: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
b4a0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
b4b0: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
b4c0: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
b4d0: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
b4e0: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
b4f0: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
b500: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
b510: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
b520: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
b530: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
b540: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
b550: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
b560: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
b570: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
b580: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
b590: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b5a0: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
b5b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b5c0: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
b5d0: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
b5e0: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
b5f0: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
b600: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
b610: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
b620: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
b630: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
b640: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b650: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
b660: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
b670: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
b680: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b690: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
b6a0: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
b6b0: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
b6c0: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
b6d0: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
b6e0: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
b6f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
b700: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
b710: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
b720: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
b730: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
b740: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b750: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
b760: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b770: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b780: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
b790: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
b7a0: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
b7b0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
b7c0: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
b7d0: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
b7e0: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
b7f0: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
b800: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
b810: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
b820: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
b830: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
b840: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
b850: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
b860: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b870: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b880: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
b890: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b8a0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
b8b0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
b8c0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
b8d0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
b8e0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
b8f0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
b900: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
b910: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
b920: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
b930: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
b940: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
b950: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
b960: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
b970: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
b980: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
b990: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
b9a0: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
b9b0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
b9c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
b9d0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
b9e0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
ba00: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ba10: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ba20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
ba30: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
ba40: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
ba50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
ba60: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
ba70: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
ba80: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
ba90: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
baa0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bab0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bac0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bad0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bae0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
baf0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bb00: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bb10: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bb20: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bb30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bb40: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bb50: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bb60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bb70: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bb80: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bb90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bba0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bbb0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bbc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bbd0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bbe0: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bbf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc00: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bc10: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bc20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc30: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bc40: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bc50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bc60: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bc70: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bc80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bc90: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
bca0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
bcb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
bcc0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
bcd0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
bce0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bcf0: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
bd00: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
bd10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
bd20: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
bd30: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
bd40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
bd50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
bd60: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
bd70: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bd80: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
bd90: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bda0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bdb0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bdc0: 32 33 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64  23./* deprecated
bdd0: 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e   names */.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
bdf0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
be00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
be10: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
be20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
be30: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
be40: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
be50: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
be60: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
be70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
be80: 20 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45            SQLITE
be90: 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e  _FCNTL_LAST_ERRN
bea0: 4f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  O../*.** CAPI3RE
beb0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
bec0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
bed0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
bee0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
bef0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
bf00: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
bf10: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
bf20: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
bf30: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
bf40: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
bf50: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
bf60: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
bf70: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
bf80: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
bf90: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
bfa0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
bfb0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
bfc0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
bfd0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
bfe0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
bff0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
c000: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c010: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
c020: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
c030: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
c040: 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a  rface Object.**.
c050: 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
c060: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c070: 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
c080: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
c090: 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51  etween.** the SQ
c0a0: 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68  Lite core and th
c0b0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  e underlying ope
c0c0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
c0d0: 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20  The "vfs".** in 
c0e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
c0f0: 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f  object stands fo
c100: 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20  r "virtual file 
c110: 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a  system".  See.**
c120: 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20   the [VFS | VFS 
c130: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66  documentation] f
c140: 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72  or further infor
c150: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
c160: 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69  e value of the i
c170: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73  Version field is
c180: 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74   initially 1 but
c190: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69   may be larger i
c1a0: 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73  n.** future vers
c1b0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ions of SQLite. 
c1c0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   Additional fiel
c1d0: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c1e0: 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62  ed to this.** ob
c1f0: 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56  ject when the iV
c200: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20  ersion value is 
c210: 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65  increased.  Note
c220: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
c230: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
c240: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c250: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
c260: 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77  transaction betw
c270: 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  een.** SQLite ve
c280: 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20  rsion 3.5.9 and 
c290: 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68  3.6.0 and yet th
c2a0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
c2b0: 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69   was not.** modi
c2c0: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fied..**.** The 
c2d0: 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69  szOsFile field i
c2e0: 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
c2f0: 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71  e subclassed [sq
c300: 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73  lite3_file].** s
c310: 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79  tructure used by
c320: 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61   this VFS.  mxPa
c330: 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61  thname is the ma
c340: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a  ximum length of.
c350: 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e  ** a pathname in
c360: 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a   this VFS..**.**
c370: 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69   Registered sqli
c380: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20  te3_vfs objects 
c390: 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69  are kept on a li
c3a0: 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64  nked list formed
c3b0: 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74   by.** the pNext
c3c0: 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b   pointer.  The [
c3d0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
c3e0: 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  ster()].** and [
c3f0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
c400: 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66  gister()] interf
c410: 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73  aces manage this
c420: 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68   list.** in a th
c430: 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20  read-safe way.  
c440: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
c450: 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61  _find()] interfa
c460: 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74  ce.** searches t
c470: 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65  he list.  Neithe
c480: 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
c490: 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56  n code nor the V
c4a0: 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  FS.** implementa
c4b0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20  tion should use 
c4c0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
c4d0: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65  r..**.** The pNe
c4e0: 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  xt field is the 
c4f0: 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68  only field in th
c500: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c510: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c520: 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72  SQLite will ever
c530: 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65   modify.  SQLite
c540: 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73   will only acces
c550: 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74  s.** or modify t
c560: 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20  his field while 
c570: 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63  holding a partic
c580: 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65  ular static mute
c590: 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  x..** The applic
c5a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
c5b0: 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69  er modify anythi
c5c0: 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71  ng within the sq
c5d0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a  lite3_vfs.** obj
c5e0: 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a  ect once the obj
c5f0: 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67  ect has been reg
c600: 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  istered..**.** T
c610: 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68  he zName field h
c620: 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  olds the name of
c630: 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e   the VFS module.
c640: 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a    The name must.
c650: 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72  ** be unique acr
c660: 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75  oss all VFS modu
c670: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  les..**.** [[sql
c680: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d  ite3_vfs.xOpen]]
c690: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
c6a0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
c6b0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c6c0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20  ter to xOpen.** 
c6d0: 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  is either a NULL
c6e0: 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69   pointer or stri
c6f0: 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ng obtained.** f
c700: 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  rom xFullPathnam
c710: 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69  e() with an opti
c720: 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65  onal suffix adde
c730: 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66  d..** ^If a suff
c740: 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74  ix is added to t
c750: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c760: 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a  ameter, it will.
c770: 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20  ** consist of a 
c780: 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61  single "-" chara
c790: 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79  cter followed by
c7a0: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a   no more than.**
c7b0: 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   11 alphanumeric
c7c0: 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72   and/or "-" char
c7d0: 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69  acters..** ^SQLi
c7e0: 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61  te further guara
c7f0: 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  ntees that.** th
c800: 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
c810: 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61   valid and uncha
c820: 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73  nged until xClos
c830: 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  e() is.** called
c840: 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65  . Because of the
c850: 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
c860: 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ce,.** the [sqli
c870: 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61  te3_file] can sa
c880: 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69  fely store a poi
c890: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66  nter to the.** f
c8a0: 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65  ilename if it ne
c8b0: 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  eds to remember 
c8c0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72  the filename for
c8d0: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a   some reason..**
c8e0: 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   If the zFilenam
c8f0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c900: 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70  Open is a NULL p
c910: 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65  ointer then xOpe
c920: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74  n.** must invent
c930: 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61   its own tempora
c940: 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20  ry name for the 
c950: 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72  file.  ^Whenever
c960: 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61   the .** xFilena
c970: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  me parameter is 
c980: 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73  NULL it will als
c990: 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  o be the case th
c9a0: 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20  at the.** flags 
c9b0: 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69  parameter will i
c9c0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
c9d0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
c9e0: 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  E]..**.** The fl
c9f0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
ca00: 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73  xOpen() includes
ca10: 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e   all bits set in
ca20: 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72  .** the flags ar
ca30: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
ca40: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20  e3_open_v2()].  
ca50: 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f  Or if [sqlite3_o
ca60: 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  pen()].** or [sq
ca70: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
ca80: 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c  is used, then fl
ca90: 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20  ags includes at 
caa0: 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  least.** [SQLITE
cab0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
cac0: 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
cad0: 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20  CREATE]. .** If 
cae0: 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20  xOpen() opens a 
caf0: 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74  file read-only t
cb00: 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75  hen it sets *pOu
cb10: 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63  tFlags to.** inc
cb20: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
cb30: 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74  N_READONLY].  Ot
cb40: 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75  her bits in *pOu
cb50: 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65  tFlags may be se
cb60: 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74  t..**.** ^(SQLit
cb70: 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20  e will also add 
cb80: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
cb90: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
cba0: 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c  e xOpen().** cal
cbb0: 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  l, depending on 
cbc0: 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67  the object being
cbd0: 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c   opened:.**.** <
cbe0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  ul>.** <li>  [SQ
cbf0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
cc00: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
cc10: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
cc20: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cc30: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
cc40: 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  P_DB].** <li>  [
cc50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cc60: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
cc70: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cc80: 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a  TRANSIENT_DB].**
cc90: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cca0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a  PEN_SUBJOURNAL].
ccb0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ccc0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
ccd0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d  SQLITE_OPEN_WAL]
ccf0: 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
cd00: 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69  * The file I/O i
cd10: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61  mplementation ca
cd20: 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74  n use the object
cd30: 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a   type flags to.*
cd40: 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79  * change the way
cd50: 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66   it deals with f
cd60: 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70  iles.  For examp
cd70: 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
cd80: 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20  on.** that does 
cd90: 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63  not care about c
cda0: 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72  rash recovery or
cdb0: 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   rollback might 
cdc0: 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e  make.** the open
cdd0: 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69   of a journal fi
cde0: 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69  le a no-op.  Wri
cdf0: 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72  tes to this jour
ce00: 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73  nal would.** als
ce10: 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64  o be no-ops, and
ce20: 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   any attempt to 
ce30: 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c  read the journal
ce40: 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a   would return.**
ce50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20   SQLITE_IOERR.  
ce60: 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  Or the implement
ce70: 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f  ation might reco
ce80: 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74  gnize that a dat
ce90: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69  abase.** file wi
cea0: 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65  ll be doing page
ceb0: 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20  -aligned sector 
cec0: 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73  reads and writes
ced0: 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20   in a random.** 
cee0: 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70  order and set up
cef0: 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74   its I/O subsyst
cf00: 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a  em accordingly..
cf10: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67  **.** SQLite mig
cf20: 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ht also add one 
cf30: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
cf40: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
cf50: 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  pen method:.**.*
cf60: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
cf70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cf80: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c  TEONCLOSE].** <l
cf90: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
cfa0: 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f  EXCLUSIVE].** </
cfb0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ul>.**.** The [S
cfc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
cfd0: 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d  EONCLOSE] flag m
cfe0: 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68  eans the file sh
cff0: 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74  ould be.** delet
d000: 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c  ed when it is cl
d010: 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c  osed.  ^The [SQL
d020: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
d030: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20  NCLOSE].** will 
d040: 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20  be set for TEMP 
d050: 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68  databases and th
d060: 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72  eir journals, tr
d070: 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62  ansient.** datab
d080: 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75  ases, and subjou
d090: 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rnals..**.** ^Th
d0a0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  e [SQLITE_OPEN_E
d0b0: 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69  XCLUSIVE] flag i
d0c0: 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e  s always used in
d0d0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20   conjunction.** 
d0e0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
d0f0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c  _OPEN_CREATE] fl
d100: 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f  ag, which are bo
d110: 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61  th directly.** a
d120: 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20  nalogous to the 
d130: 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45  O_EXCL and O_CRE
d140: 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20  AT flags of the 
d150: 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20  POSIX open().** 
d160: 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45  API.  The SQLITE
d170: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
d180: 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65  flag, when paire
d190: 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53  d with the .** S
d1a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
d1b0: 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e  E, is used to in
d1c0: 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65  dicate that file
d1d0: 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a   should always.*
d1e0: 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e  * be created, an
d1f0: 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20  d that it is an 
d200: 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65  error if it alre
d210: 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49  ady exists..** I
d220: 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20  t is <i>not</i> 
d230: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
d240: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d250: 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66   be opened .** f
d260: 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63  or exclusive acc
d270: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c  ess..**.** ^At l
d280: 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79  east szOsFile by
d290: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72  tes of memory ar
d2a0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
d2b0: 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64  QLite.** to hold
d2c0: 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66   the  [sqlite3_f
d2d0: 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70  ile] structure p
d2e0: 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
d2f0: 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  rd.** argument t
d300: 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f  o xOpen.  The xO
d310: 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20  pen method does 
d320: 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61  not have to.** a
d330: 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75  llocate the stru
d340: 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64  cture; it should
d350: 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e   just fill it in
d360: 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20  .  Note that.** 
d370: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d380: 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71   must set the sq
d390: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
d3a0: 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a  ods to either.**
d3b0: 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65   a valid [sqlite
d3c0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
d3d0: 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e  ject or to NULL.
d3e0: 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a    xOpen must do.
d3f0: 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20  ** this even if 
d400: 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20  the open fails. 
d410: 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20   SQLite expects 
d420: 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33  that the sqlite3
d430: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a  _file.pMethods.*
d440: 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62  * element will b
d450: 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f  e valid after xO
d460: 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61  pen returns rega
d470: 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
d480: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c  ccess.** or fail
d490: 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e  ure of the xOpen
d4a0: 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73   call..**.** [[s
d4b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65  qlite3_vfs.xAcce
d4c0: 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61  ss]].** ^The fla
d4d0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
d4e0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
d4f0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
d500: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
d510: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
d520: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
d530: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d540: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
d550: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
d560: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
d570: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
d580: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
d590: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
d5a0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
d5b0: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
d5c0: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
d5d0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
d5e0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
d5f0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77  ^SQLite will alw
d600: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
d610: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
d620: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
d630: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
d640: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
d650: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
d660: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
d670: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
d680: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
d690: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
d6a0: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
d6b0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d6c0: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
d6d0: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
d6e0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
d6f0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
d700: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
d710: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
d720: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
d730: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
d740: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
d750: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
d760: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
d770: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
d780: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
d790: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
d7a0: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
d7b0: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
d7c0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
d7d0: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
d7e0: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
d7f0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
d800: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
d810: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
d820: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
d830: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
d840: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
d850: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
d860: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
d870: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
d880: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
d890: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
d8a0: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
d8b0: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
d8c0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
d8d0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
d8e0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
d8f0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
d900: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
d910: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
d920: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
d930: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
d940: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
d950: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
d960: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
d970: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
d980: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d990: 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  e().** method re
d9a0: 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44  turns a Julian D
d9b0: 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68  ay Number for th
d9c0: 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61  e current date a
d9d0: 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20  nd time as.** a 
d9e0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
d9f0: 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43  alue..** ^The xC
da00: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
da10: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
da20: 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c  , as an integer,
da30: 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44   the Julian.** D
da40: 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70  ay Number multip
da50: 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30  lied by 86400000
da60: 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   (the number of 
da70: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20  milliseconds in 
da80: 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61  .** a 24-hour da
da90: 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65  y).  .** ^SQLite
daa0: 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43   will use the xC
dab0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
dac0: 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20  ) method to get 
dad0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64  the current.** d
dae0: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20  ate and time if 
daf0: 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61  that method is a
db00: 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65  vailable (if iVe
db10: 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a  rsion is 2 or .*
db20: 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68  * greater and th
db30: 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  e function point
db40: 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20  er is not NULL) 
db50: 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61  and will fall ba
db60: 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e  ck.** to xCurren
db70: 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72  tTime() if xCurr
db80: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69  entTimeInt64() i
db90: 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a  s unavailable..*
dba0: 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79  *.** ^The xSetSy
dbb0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74  stemCall(), xGet
dbc0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e  SystemCall(), an
dbd0: 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c  d xNestSystemCal
dbe0: 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  l() interfaces.*
dbf0: 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62  * are not used b
dc00: 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  y the SQLite cor
dc10: 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  e.  These option
dc20: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
dc30: 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79  e provided.** by
dc40: 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66   some VFSes to f
dc50: 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e  acilitate testin
dc60: 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64  g of the VFS cod
dc70: 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67  e. By overriding
dc80: 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c   .** system call
dc90: 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73  s with functions
dca0: 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72   under its contr
dcb0: 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72  ol, a test progr
dcc0: 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61  am can.** simula
dcd0: 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72  te faults and er
dce0: 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74  ror conditions t
dcf0: 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77  hat would otherw
dd00: 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74  ise be difficult
dd10: 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c  .** or impossibl
dd20: 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68  e to induce.  Th
dd30: 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20  e set of system 
dd40: 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62  calls that can b
dd50: 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20  e overridden.** 
dd60: 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20  varies from one 
dd70: 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20  VFS to another, 
dd80: 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72  and from one ver
dd90: 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65  sion of the same
dda0: 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e   VFS to the.** n
ddb0: 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
ddc0: 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73  ns that use thes
ddd0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73  e interfaces mus
dde0: 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f  t be prepared fo
ddf0: 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20  r any.** or all 
de00: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  of these interfa
de10: 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f  ces to be NULL o
de20: 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61  r for their beha
de30: 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a  vior to change.*
de40: 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61  * from one relea
de50: 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20  se to the next. 
de60: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
de70: 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74  st not attempt t
de80: 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20  o access.** any 
de90: 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73  of these methods
dea0: 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   if the iVersion
deb0: 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c   of the VFS is l
dec0: 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74  ess than 3..*/.t
ded0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
dee0: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
def0: 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76  3_vfs;.typedef v
df00: 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79  oid (*sqlite3_sy
df10: 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29  scall_ptr)(void)
df20: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
df30: 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  _vfs {.  int iVe
df40: 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20  rsion;          
df50: 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76    /* Structure v
df60: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63  ersion number (c
df70: 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20  urrently 3) */. 
df80: 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20   int szOsFile;  
df90: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a            /* Siz
dfa0: 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20  e of subclassed 
dfb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a  sqlite3_file */.
dfc0: 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65    int mxPathname
dfd0: 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61  ;          /* Ma
dfe0: 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e  ximum file pathn
dff0: 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20  ame length */.  
e000: 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65  sqlite3_vfs *pNe
e010: 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74  xt;      /* Next
e020: 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20   registered VFS 
e030: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
e040: 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a  *zName;       /*
e050: 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69   Name of this vi
e060: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
e070: 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  m */.  void *pAp
e080: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
e090: 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70  /* Pointer to ap
e0a0: 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66  plication-specif
e0b0: 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74  ic data */.  int
e0c0: 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
e0d0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e0e0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e0f0: 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20  e3_file*,.      
e100: 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61           int fla
e110: 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61  gs, int *pOutFla
e120: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  gs);.  int (*xDe
e130: 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lete)(sqlite3_vf
e140: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e150: 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44  zName, int syncD
e160: 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63  ir);.  int (*xAc
e170: 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  cess)(sqlite3_vf
e180: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e190: 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73  zName, int flags
e1a0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
e1b0: 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61  .  int (*xFullPa
e1c0: 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f  thname)(sqlite3_
e1d0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e1e0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75   *zName, int nOu
e1f0: 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  t, char *zOut);.
e200: 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65    void *(*xDlOpe
e210: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
e220: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
e230: 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20  lename);.  void 
e240: 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69  (*xDlError)(sqli
e250: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
e260: 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d  yte, char *zErrM
e270: 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a  sg);.  void (*(*
e280: 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f  xDlSym)(sqlite3_
e290: 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73  vfs*,void*, cons
e2a0: 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29  t char *zSymbol)
e2b0: 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20  )(void);.  void 
e2c0: 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69  (*xDlClose)(sqli
e2d0: 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29  te3_vfs*, void*)
e2e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f  ;.  int (*xRando
e2f0: 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  mness)(sqlite3_v
e300: 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
e310: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69  char *zOut);.  i
e320: 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c  nt (*xSleep)(sql
e330: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
e340: 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20  icroseconds);.  
e350: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e360: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e370: 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e  , double*);.  in
e380: 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f  t (*xGetLastErro
e390: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e3a0: 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20   int, char *);. 
e3b0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e3c0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e3d0: 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74  n version 1 of t
e3e0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e3f0: 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69  ject.  ** defini
e400: 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61  tion.  Those tha
e410: 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64  t follow are add
e420: 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20  ed in version 2 
e430: 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20  or later.  */.  
e440: 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69  int (*xCurrentTi
e450: 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33  meInt64)(sqlite3
e460: 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69  _vfs*, sqlite3_i
e470: 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  nt64*);.  /*.  *
e480: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
e490: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
e4a0: 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74  ons 1 and 2 of t
e4b0: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
e4c0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65  ject..  ** Those
e4d0: 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76   below are for v
e4e0: 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65  ersion 3 and gre
e4f0: 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74  ater..  */.  int
e500: 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c   (*xSetSystemCal
e510: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e520: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e530: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63  me, sqlite3_sysc
e540: 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69  all_ptr);.  sqli
e550: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20  te3_syscall_ptr 
e560: 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xGetSystemCall
e570: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e580: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e590: 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  e);.  const char
e5a0: 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43   *(*xNextSystemC
e5b0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e5c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e5d0: 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  Name);.  /*.  **
e5e0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e5f0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e600: 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f  ns 1 through 3 o
e610: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
e620: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65   object..  ** Ne
e630: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
e640: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
e650: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
e660: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
e670: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
e680: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
e690: 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a  is happens. .  *
e6a0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
e6b0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
e6c0: 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20  the xAccess VFS 
e6d0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
e6e0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
e6f0: 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64  ants can be used
e700: 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61   as the third pa
e710: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
e720: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
e730: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
e740: 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  vfs] object.  Th
e750: 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  ey determine.** 
e760: 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72  what kind of per
e770: 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63  missions the xAc
e780: 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c  cess method is l
e790: 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57  ooking for..** W
e7a0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e7b0: 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41  S_EXISTS, the xA
e7c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
e7d0: 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68  simply checks wh
e7e0: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65  ether the file e
e7f0: 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53  xists..** With S
e800: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e810: 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63  DWRITE, the xAcc
e820: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e830: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e840: 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79   named directory
e850: 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c   is both readabl
e860: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a  e and writable.*
e870: 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  * (in other word
e880: 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20  s, if files can 
e890: 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65  be added, remove
e8a0: 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77  d, and renamed w
e8b0: 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72  ithin.** the dir
e8c0: 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20  ectory)..** The 
e8d0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e8e0: 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74  ADWRITE constant
e8f0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73   is currently us
e900: 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a  ed only by the.*
e910: 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  * [temp_store_di
e920: 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c  rectory pragma],
e930: 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75   though this cou
e940: 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ld change in a f
e950: 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
e960: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57   of SQLite..** W
e970: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
e980: 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63  S_READ, the xAcc
e990: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68  ess method.** ch
e9a0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e9b0: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
e9c0: 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41  e.  The SQLITE_A
e9d0: 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74  CCESS_READ const
e9e0: 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e  ant is.** curren
e9f0: 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75  tly unused, thou
ea00: 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75  gh it might be u
ea10: 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20  sed in a future 
ea20: 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
ea30: 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
ea40: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
ea50: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
ea60: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
ea70: 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f  _READWRITE 1   /
ea80: 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41  * Used by PRAGMA
ea90: 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65   temp_store_dire
eaa0: 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ctory */.#define
eab0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
eac0: 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20  EAD      2   /* 
ead0: 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  Unused */../*.**
eae0: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
eaf0: 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63   for the xShmLoc
eb00: 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  k VFS method.**.
eb10: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
eb20: 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
eb30: 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f  e the various lo
eb40: 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73  cking operations
eb50: 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74  .** allowed by t
eb60: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
eb70: 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69  od of [sqlite3_i
eb80: 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65  o_methods].  The
eb90: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72  .** following ar
eba0: 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c  e the only legal
ebb0: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66   combinations of
ebc0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a   flags to the.**
ebd0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ebe0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
ebf0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
ec00: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
ec10: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
ec20: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
ec30: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ec40: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69  EXCLUSIVE.** <li
ec50: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
ec60: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
ec70: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
ec80: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ec90: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
eca0: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f  _EXCLUSIVE.** </
ecb0: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75  ul>.**.** When u
ecc0: 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61  nlocking, the sa
ecd0: 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43  me SHARED or EXC
ece0: 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74  LUSIVE flag must
ecf0: 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a   be supplied as.
ed00: 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20  ** was given no 
ed10: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
ed20: 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20  g lock.  .**.** 
ed30: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
ed40: 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69  hod can transiti
ed50: 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  on between unloc
ed60: 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f  ked and SHARED o
ed70: 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c  r.** between unl
ed80: 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53  ocked and EXCLUS
ed90: 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20  IVE.  It cannot 
eda0: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
edb0: 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64  en SHARED.** and
edc0: 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23   EXCLUSIVE..*/.#
edd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
ede0: 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31  M_UNLOCK       1
edf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ee00: 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  SHM_LOCK        
ee10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
ee20: 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20  E_SHM_SHARED    
ee30: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
ee40: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
ee50: 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41  E    8../*.** CA
ee60: 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20  PI3REF: Maximum 
ee70: 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a  xShmLock index.*
ee80: 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
ee90: 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c  k method on [sql
eea0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
eeb0: 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a   may use values.
eec0: 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ** between 0 and
eed0: 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e   this upper boun
eee0: 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74  d as its "offset
eef0: 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54  " argument..** T
ef00: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77  he SQLite core w
ef10: 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70  ill never attemp
ef20: 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20  t to acquire or 
ef30: 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63  release a.** loc
ef40: 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69  k outside of thi
ef50: 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69  s range.*/.#defi
ef60: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c  ne SQLITE_SHM_NL
ef70: 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f  OCK        8.../
ef80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
ef90: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
efa0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
efb0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
efc0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
efd0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
efe0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
eff0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
f000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f010: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
f020: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
f030: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
f040: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
f050: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f060: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
f070: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
f080: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
f090: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
f0a0: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
f0b0: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
f0c0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
f0d0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
f0e0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
f0f0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
f100: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
f110: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
f120: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
f130: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
f140: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f150: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
f160: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
f170: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
f180: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f190: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
f1a0: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
f1b0: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
f1c0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
f1d0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
f1e0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
f1f0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
f200: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
f210: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
f220: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
f230: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
f240: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
f250: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f260: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
f270: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
f280: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
f290: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f2a0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
f2b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f2c0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
f2d0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
f2e0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
f2f0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
f300: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f310: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
f320: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f330: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
f340: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
f350: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f360: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
f370: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
f380: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
f390: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
f3a0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f3b0: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
f3c0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f3d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
f3e0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
f3f0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
f400: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
f410: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
f420: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
f430: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
f440: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
f450: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
f460: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
f470: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
f480: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
f490: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
f4a0: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
f4b0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
f4c0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
f4d0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
f4e0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
f4f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f500: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
f510: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
f520: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f530: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
f540: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
f550: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
f560: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
f570: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
f580: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
f590: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
f5a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f5b0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
f5c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
f5d0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
f5e0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
f5f0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
f600: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
f610: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
f620: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
f630: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
f640: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
f650: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
f660: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
f670: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
f680: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
f690: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
f6a0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
f6b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f6c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f6d0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
f6e0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
f6f0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
f700: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
f710: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
f720: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
f730: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
f740: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
f760: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
f770: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
f780: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
f790: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f7a0: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
f7b0: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
f7c0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
f7d0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
f7e0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
f7f0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
f800: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
f810: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
f820: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
f830: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
f840: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
f850: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
f860: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
f870: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
f880: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
f890: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
f8a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f8b0: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
f8c0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
f8d0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
f8e0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f8f0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
f900: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
f910: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
f920: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
f930: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
f940: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
f950: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
f960: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
f970: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
f980: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
f990: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
f9a0: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
f9b0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
f9c0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
f9d0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
f9e0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
f9f0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
fa00: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
fa10: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
fa20: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
fa30: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
fa40: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
fa50: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
fa60: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
fa70: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
fa80: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
fa90: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
faa0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
fab0: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
fac0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
fad0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
fae0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
faf0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
fb00: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
fb10: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
fb20: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
fb30: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
fb40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
fb50: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
fb60: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
fb70: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
fb80: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
fb90: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
fba0: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
fbb0: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
fbc0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
fbd0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
fbe0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
fbf0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
fc00: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
fc10: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
fc20: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
fc30: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
fc40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
fc50: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
fc60: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
fc70: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
fc80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fc90: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
fca0: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
fcb0: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
fcc0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
fcd0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
fce0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
fcf0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
fd00: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
fd10: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
fd20: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
fd30: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
fd40: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
fd50: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
fd60: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
fd70: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
fd80: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd90: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
fda0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
fdb0: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
fdc0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
fdd0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
fde0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
fdf0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
fe00: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
fe10: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
fe20: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
fe30: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
fe40: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
fe50: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
fe60: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
fe70: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
fe80: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
fe90: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
fea0: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
feb0: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
fec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
fed0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
fee0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
fef0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
ff00: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
ff10: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
ff20: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
ff40: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
ff50: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
ff60: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
ff70: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
ff80: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
ff90: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
ffa0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
ffb0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
ffc0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
ffd0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
ffe0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
fff0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
10000 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
10010 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
10020 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
10030 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10040 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ary.**.** The sq
10050 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10060 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
10070 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
10080 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10090 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
100a0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
100b0 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
100c0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
100d0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
100e0 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
100f0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
10100 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
10110 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
10120 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
10130 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
10140 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
10150 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
10160 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
10170 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
10180 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
10190 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
101a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
101b0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
101c0 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
101d0 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
101e0 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
101f0 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
10200 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10210 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
10220 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
10230 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
10240 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
10250 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
10260 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
10270 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
10280 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
10290 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
102a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
102b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
102c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
102d0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
102e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
102f0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
10300 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10310 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10320 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10330 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10340 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10350 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10360 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10370 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10380 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10390 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
103a0 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
103b0 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
103c0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
103d0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
103e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
103f0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10400 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10410 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10420 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10430 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10440 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10450 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10460 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10470 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10480 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10490 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
104a0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
104b0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
104c0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
104d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
104e0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
104f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10500 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10510 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10520 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10530 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10540 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10550 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10560 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10570 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10580 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10590 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
105a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
105b0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
105c0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
105d0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
105e0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
105f0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10610 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
10620 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10630 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10640 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
10650 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
10660 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
10670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10680 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
10690 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
106a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
106b0 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
106c0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
106d0 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
106e0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
106f0 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
10700 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
10710 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
10720 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
10730 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10740 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
10750 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
10760 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
10770 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
10780 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
10790 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
107a0 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
107b0 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
107c0 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
107d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
107e0 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
107f0 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
10800 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
10810 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
10820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
10830 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
10840 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
10850 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
10860 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
10870 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
10880 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
10890 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
108a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
108b0 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
108c0 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
108d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
108e0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
108f0 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
10900 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
10910 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
10920 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
10930 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
10940 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
10950 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10960 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
10970 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
10980 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
10990 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
109a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
109b0 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
109c0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
109d0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
109e0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
109f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10a00 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
10a10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10a20 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10a30 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10a40 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10a50 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10a60 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
10a70 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10a80 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
10a90 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
10aa0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10ab0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
10ac0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10ad0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10ae0 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10af0 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10b00 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10b10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b20 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10b30 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10b40 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10b50 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10b60 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
10b70 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
10b80 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
10b90 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
10ba0 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
10bb0 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
10bc0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10bd0 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10be0 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10bf0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10c00 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
10c10 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
10c20 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10c30 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10c40 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10c50 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10c60 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
10c70 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
10c80 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
10c90 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
10ca0 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
10cb0 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
10cc0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10cd0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10ce0 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10cf0 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10d00 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
10d10 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
10d20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10d30 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10d40 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10d50 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10d60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
10d70 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
10d80 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
10d90 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
10da0 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
10db0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
10dc0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10dd0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10de0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10df0 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10e00 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10e10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10e20 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10e30 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10e40 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10e50 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10e60 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
10e70 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
10e80 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
10e90 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
10ea0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
10eb0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
10ec0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10ed0 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10ee0 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10ef0 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10f00 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10f10 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10f20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10f30 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10f40 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10f50 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10f60 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
10f70 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
10f80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10f90 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
10fa0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
10fb0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
10fc0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10fd0 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10fe0 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10ff0 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
11000 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
11010 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
11020 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
11030 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
11040 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
11050 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
11060 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11070 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
11080 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
11090 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
110a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
110b0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
110c0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
110d0 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
110e0 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
110f0 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
11100 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
11110 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
11120 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
11130 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
11140 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
11150 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
11160 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
11170 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
11180 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
11190 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
111a0 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
111b0 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
111c0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
111d0 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
111e0 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
111f0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11200 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
11210 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
11220 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
11230 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
11240 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
11250 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
11260 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
11270 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
11280 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
11290 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
112a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
112b0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
112c0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
112d0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
112e0 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
112f0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11300 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
11310 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
11320 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
11330 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
11340 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
11350 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
11360 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
11370 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
11380 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
11390 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
113a0 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
113b0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
113c0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
113d0 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
113e0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
113f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11400 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
11410 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
11420 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
11430 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
11440 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
11450 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
11460 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
11470 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
11480 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11490 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
114a0 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
114b0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
114c0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
114d0 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
114e0 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
114f0 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
11500 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
11510 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
11520 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
11530 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
11540 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
11550 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
11560 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
11570 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
11580 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
11590 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
115a0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
115b0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
115c0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
115d0 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
115e0 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
115f0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
11600 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
11610 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
11620 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
11630 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
11640 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
11650 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
11660 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
11670 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
11680 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11690 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
116a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
116b0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
116c0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
116d0 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
116e0 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
116f0 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
11700 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
11710 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
11720 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
11730 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11740 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
11750 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11760 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
11770 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
11780 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
11790 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
117a0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
117b0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
117c0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
117d0 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
117e0 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
117f0 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
11800 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11810 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
11820 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
11830 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
11840 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
11850 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
11860 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11870 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11880 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11890 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
118a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
118b0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
118c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
118d0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
118e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
118f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11900 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
11910 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
11920 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
11930 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
11940 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
11950 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
11960 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
11970 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
11980 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
11990 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
119a0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
119b0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
119c0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
119d0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
119e0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
119f0 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11a00 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
11a10 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
11a20 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11a30 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11a40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11a50 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11a60 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
11a70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
11a80 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
11a90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11aa0 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
11ab0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11ac0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11ad0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11ae0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11af0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11b00 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
11b10 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
11b20 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11b30 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11b40 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11b50 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11b60 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
11b70 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
11b80 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
11b90 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
11ba0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
11bb0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
11bc0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11bd0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11be0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11bf0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11c00 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11c10 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
11c20 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11c30 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11c40 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11c50 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11c60 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
11c70 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11c80 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
11c90 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11ca0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11cb0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
11cc0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11cd0 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11cf0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11d00 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11d10 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11d20 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11d30 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11d40 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11d50 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11d60 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
11d70 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11d80 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
11d90 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11da0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11db0 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
11dc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11dd0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11de0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11df0 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11e00 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11e10 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11e20 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11e30 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11e40 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11e50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11e60 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
11e70 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
11e80 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
11e90 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
11ea0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
11eb0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
11ec0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11ed0 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11ee0 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11ef0 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11f00 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11f10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11f20 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11f30 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11f40 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11f50 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11f60 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
11f70 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11f80 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11f90 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11fa0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
11fb0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
11fc0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11fd0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11ff0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
12000 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
12010 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
12020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12030 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
12040 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12050 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12060 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12070 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
12080 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
12090 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
120a0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
120b0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
120c0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
120d0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
120e0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
120f0 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
12100 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
12110 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
12120 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
12130 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
12140 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
12150 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
12160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
12170 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12180 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
12190 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
121a0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
121b0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
121c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
121d0 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
121e0 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
121f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12200 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
12210 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
12220 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
12230 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
12240 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12250 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
12260 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
12270 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
12280 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
12290 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
122a0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
122b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
122c0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
122d0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
122e0 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
122f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12300 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12310 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12320 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12330 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12340 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12350 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12360 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
12370 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
12380 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
12390 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
123a0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
123b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
123c0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
123d0 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
123e0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
123f0 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
12400 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12420 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
12430 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12440 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
12450 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12460 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12470 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12480 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12490 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
124a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
124b0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
124c0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
124d0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
124e0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
124f0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12500 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12510 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12520 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12530 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12540 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12550 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12560 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12570 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12580 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12590 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
125a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
125b0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
125c0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
125d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
125e0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
125f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12600 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
12610 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12620 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
12630 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12640 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
12650 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12660 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
12670 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
12680 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12690 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
126a0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
126b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
126c0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
126d0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
126e0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
126f0 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
12700 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
12710 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
12720 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
12730 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
12740 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
12750 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
12760 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
12770 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
12780 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
12790 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
127a0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
127b0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
127c0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
127d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
127e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
127f0 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
12800 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
12810 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12820 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12830 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12840 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
12850 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
12860 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
12870 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
12880 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
12890 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
128a0 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
128b0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
128c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
128d0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
128e0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
128f0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
12900 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
12910 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
12920 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
12930 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12940 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
12950 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
12960 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
12970 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
12980 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
12990 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
129a0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
129b0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
129c0 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
129d0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
129e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
129f0 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
12a00 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
12a10 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
12a20 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
12a30 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
12a40 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
12a50 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12a60 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
12a70 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
12a80 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
12a90 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12ab0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12ac0 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
12ad0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12ae0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12af0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12b00 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12b10 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
12b20 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12b30 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
12b40 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
12b50 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
12b60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
12b70 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
12b80 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
12b90 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
12ba0 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
12bb0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
12bc0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
12bd0 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
12be0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
12bf0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
12c00 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
12c10 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
12c20 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12c30 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
12c40 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12c50 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12c60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
12c70 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
12c80 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
12c90 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
12ca0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
12cb0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
12cc0 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
12cd0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12ce0 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
12cf0 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
12d00 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
12d10 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
12d20 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
12d30 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12d40 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
12d50 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
12d60 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
12d70 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
12d80 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
12d90 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
12da0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
12db0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
12dc0 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
12dd0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
12de0 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
12df0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
12e00 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
12e10 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
12e20 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
12e30 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
12e40 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
12e50 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12e60 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
12e70 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12e80 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
12e90 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
12ea0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12eb0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12ec0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12ed0 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
12ee0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12ef0 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
12f00 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
12f10 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12f20 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12f30 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12f40 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12f50 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12f60 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
12f70 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12f80 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
12f90 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
12fa0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
12fb0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
12fc0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12fd0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12fe0 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
12ff0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
13000 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
13010 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
13020 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
13030 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
13040 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
13050 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
13060 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
13070 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
13080 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
13090 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
130a0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
130b0 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
130c0 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
130d0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
130e0 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
130f0 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
13100 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
13110 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
13120 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
13130 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
13140 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
13150 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
13160 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
13170 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
13180 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
13190 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
131a0 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
131b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
131c0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
131d0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
131e0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
131f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
13200 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
13210 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
13220 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
13230 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
13240 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
13250 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
13260 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
13270 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
13280 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
13290 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
132a0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
132b0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
132c0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
132d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
132e0 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
132f0 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
13300 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
13310 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
13320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
13330 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
13340 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
13350 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13360 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13370 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
13380 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
13390 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
133a0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
133b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
133c0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
133d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
133e0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
133f0 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
13400 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
13410 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
13420 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
13430 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
13440 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
13450 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
13460 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
13470 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13480 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
13490 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
134a0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
134b0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
134c0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
134d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
134e0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
134f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
13500 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
13510 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
13520 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13530 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
13540 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
13550 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
13560 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
13570 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
13580 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
13590 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
135a0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
135b0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
135c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
135d0 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
135e0 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
135f0 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
13600 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
13610 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
13620 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13630 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
13640 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13650 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
13660 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13670 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
13680 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
13690 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
136a0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
136b0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
136c0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
136d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
136e0 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
136f0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
13700 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
13710 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
13720 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
13730 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
13740 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
13750 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
13760 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
13770 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
13780 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
13790 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
137a0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
137b0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
137c0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
137d0 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
137e0 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
137f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13800 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
13810 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13820 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
13830 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13840 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13850 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13860 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13870 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
13880 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13890 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
138a0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
138b0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
138c0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
138d0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
138e0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
138f0 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
13900 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
13910 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13920 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
13930 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
13940 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
13950 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13960 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13970 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
13980 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
13990 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
139a0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
139b0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
139c0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
139d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
139e0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
139f0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13a00 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13a10 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13a20 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13a30 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13a40 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13a50 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13a60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13a70 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
13a80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
13a90 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
13aa0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
13ab0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13ac0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
13ad0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13ae0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
13af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13b00 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
13b10 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13b20 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13b30 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13b40 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13b50 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
13b60 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13b70 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
13b80 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
13b90 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13ba0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
13bb0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
13bc0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13bd0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
13be0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13bf0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13c00 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13c10 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13c20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13c30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13c40 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13c50 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13c60 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
13c70 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
13c80 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
13c90 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
13ca0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
13cb0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
13cc0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13cd0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13ce0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13cf0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13d00 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13d10 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13d20 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13d30 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13d40 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13d50 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13d60 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
13d70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13d80 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
13d90 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
13da0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
13db0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
13dc0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13dd0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13de0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13df0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13e00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13e10 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13e20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
13e30 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
13e40 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
13e50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
13e60 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
13e70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13e80 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
13e90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13ea0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
13eb0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
13ec0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
13ed0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
13ee0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
13ef0 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
13f00 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
13f10 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
13f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13f30 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
13f40 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13f50 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
13f60 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
13f70 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
13f80 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
13f90 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
13fa0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13fb0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13fc0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13fd0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
13fe0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
13ff0 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
14000 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
14010 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14020 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
14030 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14040 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
14050 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
14060 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14070 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
14080 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
14090 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
140a0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
140b0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
140c0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
140d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
140e0 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
140f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14100 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
14110 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
14120 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
14130 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
14140 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
14150 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
14160 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14170 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14190 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
141a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
141b0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
141c0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
141d0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
141e0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
141f0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14200 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14210 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
14220 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
14230 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
14240 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
14250 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
14260 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
14280 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14290 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
142a0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
142b0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
142c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
142d0 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
142e0 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
142f0 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
14300 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14310 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
14320 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
14330 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
14340 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
14350 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
14360 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
14370 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
14380 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
14390 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
143a0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
143b0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
143c0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
143d0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
143e0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
143f0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
14400 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
14410 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
14420 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
14430 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
14440 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
14450 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
14460 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
14470 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
14480 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
14490 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
144a0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
144b0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
144c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
144d0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
144e0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
144f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
14500 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
14510 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
14520 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
14530 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
14540 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
14550 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
14560 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
14570 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
14580 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
14590 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
145a0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
145b0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
145c0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
145d0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
145e0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
145f0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
14600 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
14610 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
14620 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
14630 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
14640 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
14650 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
14660 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
14670 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
14680 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14690 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
146a0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
146b0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
146c0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
146d0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
146e0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
146f0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
14700 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
14710 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
14720 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
14730 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
14740 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14750 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
14760 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14770 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69  URI.** <dd>^(Thi
14780 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
14790 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
147a0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
147b0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
147c0 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
147d0 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
147e0 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
147f0 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
14800 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
14810 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
14820 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
14830 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14840 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
14850 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
14860 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
14870 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
14880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
14890 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
148a0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
148b0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
148c0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
148d0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
148e0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
148f0 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
14900 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
14910 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
14920 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
14930 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
14940 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
14950 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
14960 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
14970 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
14980 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
14990 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
149a0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
149b0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
149c0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
149d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
149e0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
149f0 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14a00 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14a10 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14a20 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14a30 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14a40 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14a50 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14a60 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
14a70 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
14a80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14a90 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
14aa0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
14ab0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
14ac0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14ad0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  N.** <dd>^This o
14ae0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14af0 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
14b00 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14b10 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
14b20 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
14b30 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
14b40 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
14b50 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14b60 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
14b70 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
14b80 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
14b90 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75  zer.  ^The defau
14ba0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
14bb0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
14bc0 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
14bd0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14be0 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
14bf0 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
14c00 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
14c10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14c20 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
14c30 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
14c40 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
14c50 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
14c60 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
14c70 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
14c80 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
14c90 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
14ca0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
14cb0 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
14cc0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
14cd0 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14ce0 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
14cf0 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
14d00 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
14d10 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
14d20 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
14d30 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
14d40 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
14d50 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
14d60 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
14d70 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
14d80 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
14d90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14da0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
14db0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14dc0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
14dd0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14de0 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
14df0 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
14e00 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
14e10 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
14e20 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
14e30 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
14e40 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
14e50 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
14e60 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14e70 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
14e80 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
14e90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14ea0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
14eb0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
14ec0 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
14ed0 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
14ee0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
14ef0 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
14f00 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14f10 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
14f20 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
14f30 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
14f40 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
14f50 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
14f60 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
14f70 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
14f80 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
14f90 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
14fa0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
14fb0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
14fc0 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
14fd0 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
14fe0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14ff0 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
15000 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
15010 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
15020 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
15030 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
15040 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
15050 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
15060 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
15070 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
15080 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
15090 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
150a0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
150b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
150c0 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
150d0 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
150e0 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
150f0 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
15100 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
15110 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
15120 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
15130 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
15140 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
15150 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
15160 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
15170 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
15180 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
15190 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
151a0 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
151b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
151c0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
151d0 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
151e0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
151f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
15200 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
15210 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
15220 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
15230 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
15240 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
15250 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
15260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15270 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
15280 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
15290 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
152a0 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
152b0 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
152c0 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
152d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
152e0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
152f0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15300 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15310 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
15320 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15330 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
15340 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
15350 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
15360 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
15370 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
15380 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
15390 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
153a0 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
153b0 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
153c0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
153d0 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
153e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
153f0 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
15400 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
15410 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
15420 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
15430 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
15440 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
15450 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
15460 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
15470 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
15480 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
15490 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
154a0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
154b0 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
154c0 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
154d0 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
154e0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
154f0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15500 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
15510 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
15520 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
15530 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
15540 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
15550 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15560 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
15570 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
15580 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
15590 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
155a0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
155b0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
155c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
155d0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
155e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
155f0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
15600 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15610 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15620 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  E.** <dd>^This o
15630 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
15640 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
15650 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  e is compiled fo
15660 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74  r Windows.** wit
15670 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
15680 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
15690 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
156a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49  defined..** SQLI
156b0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
156c0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
156d0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
156e0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
156f0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
15700 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
15710 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
15720 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   heap..** </dl>.
15730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15740 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
15750 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
15760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15770 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
15780 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
15790 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
157a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
157b0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
157c0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
157d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
157e0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
157f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15800 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
15810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15820 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
15830 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
15840 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
15850 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15860 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
15870 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
15880 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
15890 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
158a0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
158b0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
158c0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
158d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
158e0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
158f0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
15900 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
15910 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
15920 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
15930 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
15940 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
15950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15960 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
15970 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
15980 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
15990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
159a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
159b0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
159c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
159d0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
159e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
159f0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
15a00 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
15a10 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
15a20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15a30 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
15a40 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
15a50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a60 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
15a70 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
15a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15a90 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
15aa0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
15ab0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15ac0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
15ad0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
15ae0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b00 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
15b10 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
15b20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15b30 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
15b40 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
15b50 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
15b60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15b70 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15b80 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
15b90 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
15ba0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
15bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
15bc0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15bd0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
15be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15bf0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
15c00 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
15c10 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
15c20 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15c30 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
15c40 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
15c50 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
15c60 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
15c70 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15c80 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
15c90 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
15ca0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
15cb0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
15cc0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
15cd0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
15ce0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15cf0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
15d00 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
15d10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15d20 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
15d30 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
15d40 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15d50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
15d60 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
15d70 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
15d80 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
15d90 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
15da0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
15db0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
15dc0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
15dd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15de0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
15df0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
15e00 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
15e10 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
15e20 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
15e30 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15e40 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
15e50 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15e60 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
15e70 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
15e80 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
15e90 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
15ea0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
15eb0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
15ec0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15ed0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15ee0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15ef0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
15f00 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
15f10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15f20 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15f30 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15f40 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15f50 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15f60 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
15f70 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
15f80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
15f90 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
15fa0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
15fb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15fc0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15fd0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15fe0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15ff0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
16000 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
16010 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
16020 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
16030 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
16040 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
16050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16060 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
16070 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
16080 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
16090 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
160a0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
160b0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
160c0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
160d0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
160e0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
160f0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
16100 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
16110 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
16120 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
16130 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
16140 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
16150 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16160 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
16170 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16180 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16190 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
161a0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
161b0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
161c0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
161d0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
161e0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
161f0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
16200 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
16210 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
16220 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
16230 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
16240 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
16250 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
16260 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
16270 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
16280 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
16290 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
162a0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
162b0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
162c0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
162d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
162e0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
162f0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
16300 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
16310 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
16320 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
16330 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
16340 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
16350 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
16360 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
16370 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
16380 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
16390 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
163a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
163b0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
163c0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
163d0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
163e0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
163f0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
16400 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
16410 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
16420 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
16430 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
16440 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
16450 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
16460 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
16470 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16480 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16490 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
164a0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
164b0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
164c0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
164d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
164e0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
164f0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
16500 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
16510 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
16520 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
16530 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
16540 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
16550 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
16560 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
16570 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
16580 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
16590 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
165a0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
165b0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
165c0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
165d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
165e0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
165f0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16600 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
16610 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
16620 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
16630 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
16640 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
16650 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
16660 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
16670 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
16680 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
16690 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
166a0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
166b0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
166c0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
166d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
166e0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
166f0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
16700 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
16710 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
16720 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
16730 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
16740 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
16750 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
16760 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
16770 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
16780 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
16790 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
167a0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
167b0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
167c0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
167d0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
167e0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
167f0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
16800 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
16810 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
16820 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
16830 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
16840 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
16850 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
16860 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
16870 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
16880 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
16890 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
168a0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
168b0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
168c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
168d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
168e0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
168f0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
16900 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
16910 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
16920 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
16930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16940 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16950 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
16960 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
16970 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16980 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16990 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
169a0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
169b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
169c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
169d0 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
169e0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
169f0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
16a00 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
16a10 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
16a20 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
16a30 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
16a40 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
16a50 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
16a60 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
16a70 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
16a80 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
16a90 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
16aa0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
16ab0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
16ac0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
16ad0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
16ae0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
16af0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
16b00 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
16b10 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
16b20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
16b30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
16b40 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
16b50 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
16b60 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
16b70 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
16b80 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
16b90 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
16ba0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
16bb0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
16bc0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
16bd0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
16be0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
16bf0 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
16c00 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
16c10 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
16c20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
16c30 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
16c40 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
16c50 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
16c60 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
16c70 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
16c80 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
16c90 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
16ca0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
16cb0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
16cc0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
16cd0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
16ce0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
16cf0 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
16d00 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
16d10 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
16d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
16d30 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
16d40 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
16d50 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
16d60 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
16d70 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
16d80 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
16d90 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
16da0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
16db0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
16dc0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
16dd0 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
16de0 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
16df0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
16e00 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
16e10 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
16e20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
16e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
16e40 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
16e50 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
16e60 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
16e70 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
16e80 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
16e90 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
16ea0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
16eb0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
16ec0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
16ed0 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
16ee0 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
16ef0 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
16f00 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
16f10 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
16f20 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
16f30 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
16f40 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
16f50 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
16f60 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
16f70 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
16f80 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
16f90 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
16fa0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
16fb0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
16fc0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
16fd0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16fe0 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
16ff0 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
17000 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
17010 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
17020 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
17030 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
17040 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
17050 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
17060 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
17070 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17080 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
17090 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
170a0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
170b0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
170c0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
170d0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
170e0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
170f0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
17100 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
17110 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
17120 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
17130 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
17140 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
17150 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
17160 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
17170 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
17180 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
17190 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
171a0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
171b0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
171c0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
171d0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
171e0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
171f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
17200 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
17210 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
17220 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
17230 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
17240 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
17250 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
17260 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
17270 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
17280 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
17290 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
172a0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
172b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
172c0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
172d0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
172e0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
172f0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
17300 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17310 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
17320 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
17330 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
17340 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
17350 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
17360 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
17370 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
17380 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
17390 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
173a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
173b0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
173c0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
173d0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
173e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
173f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
17400 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17410 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
17420 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
17430 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
17440 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
17450 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
17460 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
17470 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
17480 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
17490 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
174a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
174b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
174c0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
174d0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
174e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
174f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17500 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
17510 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
17520 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
17530 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
17540 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
17550 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
17560 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
17570 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
17580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17590 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
175a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
175b0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
175c0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
175d0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
175e0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
175f0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
17600 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
17610 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
17620 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
17630 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
17640 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
17650 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17660 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
17670 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
17680 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
17690 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
176a0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
176b0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
176c0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
176d0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
176e0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
176f0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
17700 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
17710 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
17720 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
17730 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
17740 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
17750 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
17760 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
17770 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
17780 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
17790 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
177a0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
177b0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
177c0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
177d0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
177e0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
177f0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
17800 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
17810 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
17820 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
17830 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
17840 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
17850 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
17860 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
17870 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
17880 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
17890 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
178a0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
178b0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
178c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
178d0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
178e0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
178f0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
17900 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
17910 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
17920 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
17930 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
17940 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
17950 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
17960 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
17970 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
17980 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
17990 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
179a0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
179b0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
179c0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
179d0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
179e0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
179f0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
17a00 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
17a10 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
17a20 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
17a30 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
17a40 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
17a50 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
17a60 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
17a70 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
17a80 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
17a90 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
17aa0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
17ab0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
17ac0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
17ad0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17ae0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
17af0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
17b00 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
17b10 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
17b20 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
17b30 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
17b40 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
17b50 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
17b60 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
17b70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
17b80 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
17b90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17ba0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
17bb0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
17bc0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
17bd0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17be0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
17bf0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
17c00 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
17c10 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
17c20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
17c30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
17c40 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
17c50 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
17c60 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
17c70 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
17c80 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
17c90 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
17ca0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
17cb0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
17cc0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
17cd0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
17ce0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
17cf0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
17d00 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
17d10 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
17d20 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
17d30 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
17d40 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
17d50 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
17d60 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
17d70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
17d80 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
17d90 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
17da0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
17db0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
17dc0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17dd0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17de0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17df0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17e00 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17e10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17e20 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17e30 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
17e40 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
17e50 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
17e60 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
17e70 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
17e80 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
17e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
17ea0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
17eb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17ec0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
17ed0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
17ee0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17ef0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17f00 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
17f10 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
17f20 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
17f30 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
17f40 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
17f50 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
17f60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
17f70 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
17f80 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
17f90 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
17fa0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
17fb0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
17fc0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
17fd0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17fe0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
17ff0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
18000 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
18010 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
18020 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
18030 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
18040 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
18050 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
18060 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
18070 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
18080 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
18090 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
180a0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
180b0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
180c0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
180d0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
180e0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
180f0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18100 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
18110 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
18120 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
18130 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
18140 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
18150 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
18160 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
18170 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18180 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
18190 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
181a0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
181b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
181c0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
181d0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
181e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
181f0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
18200 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
18210 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
18220 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
18230 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18240 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18250 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18260 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18270 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18280 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18290 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
182a0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
182b0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
182c0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
182d0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
182e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
182f0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18300 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18310 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18320 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18330 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18340 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18350 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18360 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18370 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18380 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18390 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
183a0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
183b0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
183c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
183d0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
183e0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
183f0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
18400 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
18410 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
18420 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
18430 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
18440 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
18450 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
18460 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
18470 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
18480 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
18490 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
184a0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
184b0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
184c0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
184d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
184e0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
184f0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
18500 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
18510 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
18520 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
18530 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
18540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
18550 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
18560 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
18570 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
18580 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
18590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
185a0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
185b0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
185c0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
185d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
185e0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
185f0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
18600 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
18610 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
18620 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
18630 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18640 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
18650 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
18660 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
18670 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
18680 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
18690 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
186a0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
186b0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
186c0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
186d0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
186e0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
186f0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
18700 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
18710 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
18720 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
18730 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
18740 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
18750 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
18760 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
18770 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
18780 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
18790 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
187a0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
187b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
187c0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
187d0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
187e0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
187f0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
18800 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
18810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18820 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
18830 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
18840 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
18850 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
18860 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
18870 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
18880 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
18890 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
188a0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
188b0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
188c0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
188d0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
188e0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
188f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
18900 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
18910 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18920 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18930 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
18940 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
18950 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18960 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
18970 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
18980 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
18990 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
189a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
189b0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
189c0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
189d0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
189e0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
189f0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
18a00 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
18a10 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
18a20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
18a30 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
18a40 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
18a50 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
18a60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18a70 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
18a80 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
18a90 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
18aa0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
18ab0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
18ac0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
18ad0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
18ae0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
18af0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18b00 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
18b10 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
18b20 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
18b30 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
18b40 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
18b50 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
18b60 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
18b70 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
18b80 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
18b90 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
18ba0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
18bb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
18bc0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
18bd0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
18be0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
18bf0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
18c00 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
18c10 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
18c20 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
18c30 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
18c40 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
18c50 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
18c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
18c70 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
18c80 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
18c90 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
18ca0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
18cb0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
18cc0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
18cd0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
18ce0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
18cf0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
18d00 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
18d10 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
18d20 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
18d30 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
18d40 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
18d50 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
18d60 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
18d70 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
18d80 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
18d90 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
18da0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
18db0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
18dc0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
18dd0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
18de0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
18df0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
18e00 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
18e10 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
18e20 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
18e30 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
18e40 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
18e50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
18e60 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
18e70 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
18e80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
18e90 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
18ea0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
18eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
18ec0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
18ed0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
18ee0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
18ef0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
18f00 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
18f10 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
18f20 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
18f30 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
18f40 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
18f50 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
18f60 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
18f70 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
18f80 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
18f90 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
18fa0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
18fb0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
18fc0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
18fd0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
18fe0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
18ff0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
19000 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
19010 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
19020 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
19030 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
19040 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
19050 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
19060 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
19070 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
19080 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
19090 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
190a0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
190b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
190c0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
190d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
190e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
190f0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
19100 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
19110 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
19120 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
19130 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
19140 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
19150 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
19160 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
19170 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
19180 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
19190 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
191a0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
191b0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
191c0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
191d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
191e0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
191f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
19200 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
19210 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
19220 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
19230 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
19240 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
19250 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
19260 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
19270 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
19280 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
19290 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
192a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
192b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
192c0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
192d0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
192e0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
192f0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
19300 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
19310 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19320 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
19330 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
19340 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19350 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
19360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19370 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19380 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19390 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
193a0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
193b0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
193c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
193d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
193e0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
193f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19400 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
19410 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19420 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
19430 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
19440 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
19450 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
19460 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
19470 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
19480 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
19490 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
194a0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
194b0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
194c0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
194d0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
194e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
194f0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
19500 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
19510 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
19520 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
19530 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
19540 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
19550 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
19560 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
19570 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
19580 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
19590 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
195a0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
195b0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
195c0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
195d0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
195e0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
195f0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
19600 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19610 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19620 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19630 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19640 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19650 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19660 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19670 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19680 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
19690 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
196a0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
196b0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
196c0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
196d0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
196e0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
196f0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
19700 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
19710 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
19720 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
19730 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
19740 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
19750 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
19760 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
19770 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
19780 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
19790 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
197a0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
197b0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
197c0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
197d0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
197e0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
197f0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
19800 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
19810 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
19820 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19830 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
19840 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
19850 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
19860 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
19870 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
19880 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
19890 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
198a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
198b0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
198c0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
198d0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
198e0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
198f0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
19900 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
19910 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
19920 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
19930 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
19940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
19950 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
19960 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
19970 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
19980 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
19990 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
199a0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
199b0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
199c0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
199d0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
199e0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
199f0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
19a00 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
19a10 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
19a20 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
19a30 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
19a40 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
19a50 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
19a60 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
19a70 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
19a80 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
19a90 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
19aa0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
19ab0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
19ac0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
19ad0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
19ae0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
19af0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
19b00 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
19b10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
19b20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
19b30 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
19b40 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
19b50 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
19b60 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
19b70 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
19b80 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
19b90 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
19ba0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
19bb0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
19bc0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
19bd0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
19be0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
19bf0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
19c00 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
19c10 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
19c20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
19c30 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
19c40 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
19c50 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
19c60 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
19c70 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
19c80 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
19c90 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
19ca0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
19cb0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
19cc0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
19cd0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
19ce0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
19cf0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
19d00 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
19d10 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
19d20 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
19d30 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
19d40 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
19d50 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
19d60 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
19d70 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
19d80 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19d90 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
19da0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
19db0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
19dc0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
19dd0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19de0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
19df0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
19e00 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
19e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19e20 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
19e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19e40 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
19e50 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
19e60 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
19e70 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
19e80 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
19e90 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
19ea0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19eb0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
19ec0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
19ed0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19ee0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
19ef0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19f00 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
19f10 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
19f20 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
19f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
19f40 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
19f50 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
19f60 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
19f70 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
19f80 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
19f90 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
19fa0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
19fb0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
19fc0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
19fd0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
19fe0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
19ff0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1a000 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1a010 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a020 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a030 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1a040 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1a050 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1a060 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1a070 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1a080 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1a090 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1a0a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1a0b0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1a0c0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
1a0d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1a0e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a0f0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a100 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a110 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1a120 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1a130 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1a140 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1a150 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1a160 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1a170 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1a180 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1a190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a1a0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
1a1b0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1a1c0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1a1d0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1a1e0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1a1f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a200 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1a210 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1a220 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1a230 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1a240 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
1a250 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1a260 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1a270 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1a280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1a290 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1a2a0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1a2b0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
1a2c0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1a2d0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1a2e0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1a2f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1a300 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1a310 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1a320 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1a330 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1a340 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1a350 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1a360 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1a370 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1a380 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1a390 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1a3a0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1a3b0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1a3c0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1a3d0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1a3e0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1a3f0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1a400 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1a410 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1a420 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1a430 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1a440 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1a450 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1a460 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1a470 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1a480 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1a490 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1a4a0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1a4b0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1a4c0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1a4d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1a4e0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1a4f0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1a500 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1a510 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a520 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1a530 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1a540 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1a550 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1a560 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1a570 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1a580 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a590 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1a5a0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1a5b0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1a5c0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1a5d0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1a5e0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1a5f0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1a600 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1a610 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1a620 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1a630 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1a640 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1a650 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1a660 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1a670 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a680 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1a690 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a6a0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1a6b0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1a6c0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1a6d0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1a6e0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1a6f0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a700 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1a710 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1a720 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a730 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1a740 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1a750 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1a770 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1a780 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1a790 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1a7a0 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1a7b0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a7c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a7d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a7e0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1a7f0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1a800 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a810 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1a820 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1a830 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1a840 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1a850 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1a860 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1a870 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a880 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1a890 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1a8a0 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1a8b0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1a8c0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1a8d0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1a8e0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1a8f0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1a900 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1a910 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1a920 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1a930 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1a940 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1a950 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a960 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a970 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1a980 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a990 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1a9a0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a9b0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1a9c0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1a9d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a9e0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1a9f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1aa00 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1aa10 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1aa20 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1aa30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1aa40 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1aa50 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1aa60 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1aa70 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1aa80 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1aa90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1aaa0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1aab0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1aac0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1aad0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1aae0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1aaf0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1ab00 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1ab10 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1ab20 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1ab30 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1ab40 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1ab50 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1ab60 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1ab70 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1ab80 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1ab90 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1aba0 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1abb0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1abc0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1abd0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1abe0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1abf0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1ac00 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1ac10 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1ac20 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1ac30 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1ac40 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1ac50 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1ac60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ac70 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1ac80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ac90 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1aca0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1acb0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1acc0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1acd0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1ace0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1acf0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1ad00 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1ad10 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1ad20 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1ad30 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1ad40 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1ad50 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1ad60 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1ad70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1ad80 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1ad90 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1ada0 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1adb0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1adc0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1add0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1ade0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1adf0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1ae00 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1ae10 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1ae20 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1ae30 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1ae40 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1ae50 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1ae60 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1ae70 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1ae80 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1ae90 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1aea0 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1aeb0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1aec0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1aed0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1aee0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1aef0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1af00 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1af10 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1af20 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1af30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1af40 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1af50 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1af60 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1af70 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1af80 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1af90 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1afa0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1afb0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1afc0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1afd0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1afe0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1aff0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1b000 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1b010 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1b020 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1b030 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1b040 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1b050 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1b060 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1b070 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1b080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b090 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1b0a0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1b0b0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1b0c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1b0d0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1b0e0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1b0f0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1b100 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1b110 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1b120 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b130 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b140 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b150 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1b160 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1b170 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1b180 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1b190 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1b1a0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1b1b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1b1c0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1b1d0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1b1e0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1b1f0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1b200 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b210 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1b220 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1b230 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1b240 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1b250 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1b260 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1b270 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1b280 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b290 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1b2a0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1b2b0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1b2c0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1b2d0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1b2e0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1b2f0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1b300 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1b310 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b320 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1b330 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1b340 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1b350 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1b360 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1b370 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1b380 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1b390 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1b3a0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1b3b0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1b3c0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1b3d0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1b3e0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1b3f0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1b400 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1b410 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1b420 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1b430 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1b440 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1b450 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1b460 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1b470 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1b480 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1b490 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1b4a0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1b4b0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1b4c0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1b4d0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1b4e0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1b4f0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1b500 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1b510 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1b520 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1b530 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1b540 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1b550 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1b560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1b570 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1b580 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1b590 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1b5a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b5b0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1b5c0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1b5d0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1b5e0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1b5f0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1b600 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1b610 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1b620 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1b630 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1b640 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b650 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1b660 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1b670 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1b680 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1b690 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1b6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b6b0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1b6c0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1b6d0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1b6e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b6f0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1b700 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1b710 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1b720 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1b730 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1b740 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1b750 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1b760 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b770 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1b780 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1b790 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1b7a0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1b7b0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1b7c0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1b7d0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1b7e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1b7f0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b800 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1b810 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1b820 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1b830 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1b840 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1b850 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1b860 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1b870 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1b880 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1b890 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1b8a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1b8b0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1b8c0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1b8d0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1b8e0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1b8f0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1b900 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1b910 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1b920 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1b930 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1b940 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1b950 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1b960 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b970 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b980 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b990 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1b9a0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1b9b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b9c0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1b9d0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1b9e0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1b9f0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1ba00 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ba10 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1ba20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1ba30 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1ba40 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ba50 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1ba60 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1ba70 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1ba80 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ba90 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1baa0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1bab0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1bac0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1bad0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1bae0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1baf0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1bb00 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1bb10 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1bb20 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1bb30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1bb40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1bb50 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1bb60 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1bb70 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1bb80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1bb90 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1bba0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1bbb0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1bbc0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1bbd0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1bbe0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1bbf0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1bc00 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1bc10 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1bc20 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1bc30 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1bc40 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1bc50 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bc60 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1bc70 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1bc80 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1bc90 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1bca0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1bcb0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1bcc0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1bcd0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1bce0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1bcf0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1bd00 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1bd10 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1bd20 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1bd30 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1bd40 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1bd50 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1bd60 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1bd70 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1bd80 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1bd90 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1bda0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1bdb0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1bdc0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1bdd0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1bde0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1bdf0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1be00 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1be10 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1be20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1be30 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1be40 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1be50 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1be60 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1be70 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1be80 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1be90 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1bea0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1beb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bec0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1bed0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1bee0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1bef0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1bf00 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1bf10 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1bf20 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1bf30 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1bf40 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1bf50 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1bf60 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1bf70 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1bf80 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1bf90 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1bfa0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1bfb0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1bfc0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1bfd0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1bfe0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1bff0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1c000 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1c010 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c020 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c030 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c040 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1c050 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c060 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1c070 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c080 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1c090 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c0a0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1c0b0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1c0c0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1c0d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c0e0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1c0f0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1c100 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1c110 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1c120 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1c130 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1c140 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1c150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1c160 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1c170 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1c180 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1c190 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1c1a0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1c1b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1c1c0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1c1d0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1c1e0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1c1f0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1c200 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1c210 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c220 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1c230 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1c240 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1c250 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1c260 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c270 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1c280 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1c290 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c2a0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1c2b0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1c2c0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1c2d0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1c2e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1c2f0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1c300 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1c310 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c320 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1c330 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1c340 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1c350 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1c360 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1c370 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1c380 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1c390 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1c3a0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1c3b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c3c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c3d0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1c3e0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1c3f0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1c400 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1c410 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1c420 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1c430 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1c440 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1c450 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1c460 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1c470 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c480 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1c490 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1c4a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1c4b0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1c4c0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1c4d0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1c4e0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1c4f0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1c500 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1c510 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1c520 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1c530 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1c540 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1c550 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1c560 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1c570 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1c580 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1c590 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1c5a0 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1c5b0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1c5c0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1c5d0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1c5e0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1c5f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1c600 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1c610 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1c620 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1c630 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1c640 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1c650 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1c660 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1c670 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1c680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c690 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1c6a0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1c6b0 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1c6c0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1c6d0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1c6e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1c6f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c700 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1c710 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c720 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c730 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c740 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c750 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1c760 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c770 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c780 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1c790 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1c7a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c7b0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1c7c0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1c7d0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1c7e0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1c7f0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1c800 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c810 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1c820 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1c830 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c840 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1c850 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1c860 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1c870 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1c880 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1c890 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1c8a0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1c8b0 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1c8c0 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1c8d0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1c8e0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1c8f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c900 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1c910 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1c920 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c930 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1c940 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1c950 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1c960 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c970 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1c980 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1c990 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1c9a0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c9b0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1c9c0 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1c9d0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c9e0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1c9f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1ca00 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1ca10 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1ca20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1ca30 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1ca40 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1ca50 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1ca60 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1ca70 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1ca80 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1ca90 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1caa0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1cab0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1cac0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1cad0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1cae0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1caf0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1cb00 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1cb10 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1cb20 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1cb30 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1cb40 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1cb50 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1cb60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1cb70 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1cb80 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1cb90 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1cba0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1cbb0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1cbc0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1cbd0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1cbe0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1cbf0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1cc00 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1cc10 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1cc20 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1cc30 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1cc40 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1cc50 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1cc60 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1cc70 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1cc80 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1cc90 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1cca0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1ccb0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1ccc0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1ccd0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1cce0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1ccf0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1cd00 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1cd10 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1cd20 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1cd30 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1cd40 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1cd50 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1cd60 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1cd70 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1cd80 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1cd90 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1cda0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1cdb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1cdc0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1cdd0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1cde0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1cdf0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1ce00 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1ce10 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1ce20 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1ce30 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ce40 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1ce50 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1ce60 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1ce70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1ce80 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1ce90 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1cea0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1ceb0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1cec0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1ced0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1cee0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1cef0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1cf00 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1cf10 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1cf20 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1cf30 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1cf40 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1cf50 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1cf60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1cf70 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1cf80 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1cf90 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1cfa0 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1cfb0 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1cfc0 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1cfd0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1cfe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1cff0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1d000 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1d010 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1d020 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1d030 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1d040 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d050 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1d060 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1d070 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1d080 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1d090 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1d0a0 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1d0b0 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1d0c0 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1d0d0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1d0e0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1d0f0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1d100 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1d110 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1d120 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1d130 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1d140 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1d150 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1d160 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1d170 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1d180 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1d190 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1d1a0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1d1b0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d1c0 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1d1d0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1d1e0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1d1f0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1d200 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1d210 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1d220 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1d230 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1d240 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1d250 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1d260 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1d270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1d280 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1d290 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1d2a0 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1d2b0 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1d2c0 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1d2d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1d2e0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1d2f0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1d300 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1d310 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1d320 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1d330 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1d340 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1d350 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d360 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1d370 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1d380 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1d390 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1d3a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d3b0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1d3c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1d3d0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1d3e0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1d3f0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1d400 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1d410 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1d420 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1d430 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1d440 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1d450 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1d460 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1d470 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1d480 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1d490 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1d4a0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1d4b0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1d4c0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1d4d0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1d4e0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1d4f0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1d500 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1d510 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1d520 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1d530 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1d540 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1d550 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1d560 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1d570 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1d580 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1d590 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1d5a0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1d5b0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1d5c0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1d5d0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1d5e0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49   buffer P..** ^I
1d5f0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
1d600 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e   one, then P can
1d610 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1d620 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
1d630 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
1d640 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
1d650 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
1d660 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
1d670 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
1d680 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74  than one, then t
1d690 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1d6a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1d6b0 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ss.** obtained f
1d6c0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1d6d0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1d6e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d6f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1d700 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1d710 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d720 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1d730 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74  N of 1 or more t
1d740 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64  hen.** the pseud
1d750 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1d760 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1d770 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1d780 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1d790 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1d7a0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1d7b0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1d7c0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1d7d0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1d7e0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1d7f0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1d800 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1d810 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1d820 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1d830 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1d840 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d850 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1d860 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1d870 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1d880 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1d890 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1d8a0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1d8b0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d8c0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1d8d0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1d8e0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1d8f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1d900 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1d910 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1d920 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1d930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1d940 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d950 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1d960 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1d970 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1d980 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1d990 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1d9a0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1d9b0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1d9c0 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1d9d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d9e0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d9f0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1da00 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1da10 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1da20 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1da30 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1da40 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1da50 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1da60 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1da70 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1da80 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1da90 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1daa0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1dab0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1dac0 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1dad0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1dae0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1daf0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1db00 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1db10 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1db20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1db30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1db40 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1db50 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1db60 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1db70 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1db80 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1db90 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1dba0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1dbb0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1dbc0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1dbd0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1dbe0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1dbf0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1dc00 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1dc10 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1dc20 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1dc30 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1dc40 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1dc50 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1dc60 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1dc70 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1dc80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1dc90 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1dca0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1dcb0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1dcc0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1dcd0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1dce0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1dcf0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1dd00 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1dd10 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1dd20 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1dd30 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1dd40 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1dd50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1dd60 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1dd70 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1dd80 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1dd90 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1dda0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1ddb0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1ddc0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1ddd0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1dde0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1ddf0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1de00 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1de10 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1de20 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1de30 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1de40 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1de50 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1de60 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1de70 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1de80 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1de90 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1dea0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1deb0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1dec0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1ded0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1dee0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1def0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1df00 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1df10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1df20 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1df30 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1df40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1df50 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1df60 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1df70 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1df80 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1df90 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1dfa0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1dfb0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1dfc0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1dfd0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1dfe0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1dff0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1e000 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1e010 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1e020 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1e030 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1e040 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1e050 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1e060 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1e070 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1e080 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1e090 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1e0a0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1e0b0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1e0c0 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1e0d0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1e0e0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1e0f0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1e100 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1e110 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1e120 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1e130 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1e140 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1e150 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1e160 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1e170 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1e180 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1e190 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1e1a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1e1b0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1e1c0 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1e1d0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1e1e0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1e1f0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1e200 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1e210 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1e220 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1e230 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1e240 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1e250 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1e260 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1e270 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1e280 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1e290 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1e2a0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1e2b0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1e2c0 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1e2d0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1e2e0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1e2f0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1e300 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1e310 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1e320 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1e330 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1e340 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1e350 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1e360 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1e370 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1e380 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1e390 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1e3a0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1e3b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1e3c0 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e3d0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1e3e0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1e3f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e400 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1e410 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1e420 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1e430 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1e440 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1e450 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1e460 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1e470 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1e480 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1e490 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1e4a0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1e4b0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1e4c0 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1e4d0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1e4e0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1e4f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e500 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1e510 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1e520 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1e530 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1e540 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1e550 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1e560 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1e570 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1e580 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1e590 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1e5a0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1e5b0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1e5c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e5d0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e5e0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e5f0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e610 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e620 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e630 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1e640 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1e650 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1e660 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e670 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1e680 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1e690 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1e6a0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1e6b0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1e6c0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1e6d0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1e6e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1e6f0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1e700 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1e710 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1e720 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1e730 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1e740 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1e750 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1e760 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1e770 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e780 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1e790 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1e7a0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1e7b0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1e7c0 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1e7d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1e7e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1e7f0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1e800 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e810 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1e820 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e830 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1e840 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1e850 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1e860 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1e870 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1e880 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1e890 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1e8a0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1e8b0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1e8c0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1e8d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1e8e0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1e8f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1e900 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1e910 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1e920 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1e930 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1e940 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1e950 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1e960 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1e970 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1e980 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e990 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e9a0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1e9b0 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1e9c0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e9d0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1e9e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e9f0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1ea00 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1ea10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ea20 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1ea30 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1ea40 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1ea50 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1ea60 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1ea70 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1ea80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ea90 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1eaa0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1eab0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1eac0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1ead0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1eae0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1eaf0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1eb00 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1eb10 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1eb20 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1eb30 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f  ed as a [SQLITE_
1eb40 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72  ROLLBACK | retur
1eb50 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20  n code].** from 
1eb60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  the [sqlite3_vta
1eb70 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
1eb80 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23   interface..*/.#
1eb90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1eba0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72  NY   1   /* Abor
1ebb0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
1ebc0 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ent with an erro
1ebd0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
1ebe0 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f  ITE_IGNORE 2   /
1ebf0 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63  * Don't allow ac
1ec00 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20  cess, but don't 
1ec10 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f  generate an erro
1ec20 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  r */../*.** CAPI
1ec30 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1ec40 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a   Action Codes.**
1ec50 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1ec60 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1ec70 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  )] interface reg
1ec80 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
1ec90 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68  k function.** th
1eca0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  at is invoked to
1ecb0 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61   authorize certa
1ecc0 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  in SQL statement
1ecd0 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a   actions.  The.*
1ece0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
1ecf0 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  er to the callba
1ed00 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1ed10 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69   code that speci
1ed20 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74  fies.** what act
1ed30 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74  ion is being aut
1ed40 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20  horized.  These 
1ed50 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20  are the integer 
1ed60 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61  action codes tha
1ed70 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  t.** the authori
1ed80 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79  zer callback may
1ed90 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a   be passed..**.*
1eda0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63  * These action c
1edb0 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69  ode values signi
1edc0 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  fy what kind of 
1edd0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20  operation is to 
1ede0 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64  be.** authorized
1edf0 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34  .  The 3rd and 4
1ee00 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
1ee10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
1ee20 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  on.** callback f
1ee30 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20  unction will be 
1ee40 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55  parameters or NU
1ee50 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  LL depending on 
1ee60 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a  which of these.*
1ee70 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20  * codes is used 
1ee80 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1ee90 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20  rameter.  ^(The 
1eea0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
1eeb0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1eec0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
1eed0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
1eee0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
1eef0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
1ef00 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
1ef10 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72  )^  ^The 6th par
1ef20 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1ef30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1ef40 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  k.** is the name
1ef50 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f   of the inner-mo
1ef60 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  st trigger or vi
1ef70 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f  ew that is respo
1ef80 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68  nsible for.** th
1ef90 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  e access attempt
1efa0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73   or NULL if this
1efb0 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
1efc0 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d  is directly from
1efd0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51  .** top-level SQ
1efe0 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  L code..*/./****
1eff0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f000 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f010 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a  ******* 3rd ****
1f020 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a  ******** 4th ***
1f030 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e  ********/.#defin
1f040 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f050 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31  INDEX          1
1f060 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1f070 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1f080 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f090 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1f0a0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20  ABLE          2 
1f0b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f0c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f0d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f0e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1f0f0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20  MP_INDEX     3  
1f100 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f110 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f120 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f130 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1f140 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20  P_TABLE     4   
1f150 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f160 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f170 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f180 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1f190 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f  _TRIGGER   5   /
1f1a0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1f1b0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f1c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f1d0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1f1e0 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a  VIEW      6   /*
1f1f0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1f200 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f210 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f220 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45  TE_CREATE_TRIGGE
1f230 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  R        7   /* 
1f240 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1f250 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f270 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20  E_CREATE_VIEW   
1f280 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56          8   /* V
1f290 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1f2a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f2b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f2c0 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
1f2d0 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61         9   /* Ta
1f2e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f2f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f310 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20  DROP_INDEX      
1f320 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64       10   /* Ind
1f330 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1f340 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f360 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ROP_TABLE       
1f370 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c      11   /* Tabl
1f380 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f390 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f3b0 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  OP_TEMP_INDEX   
1f3c0 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78     12   /* Index
1f3d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1f3e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f3f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f400 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  P_TEMP_TABLE    
1f410 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    13   /* Table 
1f420 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1f430 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f440 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f450 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1f460 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72   14   /* Trigger
1f470 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f480 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f490 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f4a0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20  TEMP_VIEW       
1f4b0 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  15   /* View Nam
1f4c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f4d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f4e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1f4f0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31  RIGGER         1
1f500 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  6   /* Trigger N
1f510 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1f520 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49  e SQLITE_DROP_VI
1f540 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37  EW            17
1f550 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f560 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f580 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20   SQLITE_INSERT  
1f590 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20               18 
1f5a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f5b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f5c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f5d0 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20  SQLITE_PRAGMA   
1f5e0 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20              19  
1f5f0 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20   /* Pragma Name 
1f600 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e      1st arg or N
1f610 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ULL */.#define S
1f620 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20  QLITE_READ      
1f630 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20             20   
1f640 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f650 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
1f660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f670 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20  LITE_SELECT     
1f680 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f            21   /
1f690 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1f6a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f6c0 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20  ITE_TRANSACTION 
1f6d0 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a           22   /*
1f6e0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1f6f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f710 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20  TE_UPDATE       
1f720 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
1f730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f740 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1f750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f760 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20  E_ATTACH        
1f770 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46         24   /* F
1f780 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e  ilename        N
1f790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f7b0 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20  _DETACH         
1f7c0 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61        25   /* Da
1f7d0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55  tabase Name   NU
1f7e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f800 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20  ALTER_TABLE     
1f810 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74       26   /* Dat
1f820 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62  abase Name   Tab
1f830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
1f850 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  EINDEX          
1f860 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65      27   /* Inde
1f870 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  x Name      NULL
1f880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
1f8a0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20  ALYZE           
1f8b0 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65     28   /* Table
1f8c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1f8d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1f8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1f8f0 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ATE_VTABLE      
1f900 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20    29   /* Table 
1f910 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
1f920 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f940 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  _VTABLE         
1f950 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   30   /* Table N
1f960 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
1f970 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1f980 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54  ine SQLITE_FUNCT
1f990 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  ION             
1f9a0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  31   /* NULL    
1f9b0 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e          Function
1f9c0 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69   Name   */.#defi
1f9d0 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f  ne SQLITE_SAVEPO
1f9e0 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33  INT            3
1f9f0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1fa00 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74         Savepoint
1fa10 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e   Name  */.#defin
1fa20 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20  e SQLITE_COPY   
1fa30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
1fa40 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20     /* No longer 
1fa50 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
1fa60 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45  SQLITE_RECURSIVE
1fa70 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20              33  
1fa80 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1fa90 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1faa0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41      */../*.** CA
1fab0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
1fac0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
1fad0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1fae0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
1faf0 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
1fb00 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
1fb10 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
1fb20 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
1fb30 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
1fb40 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
1fb50 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
1fb60 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1fb70 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
1fb80 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
1fb90 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
1fba0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
1fbb0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
1fbc0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
1fbd0 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
1fbe0 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
1fbf0 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
1fc00 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
1fc10 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
1fc20 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
1fc30 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
1fc40 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
1fc50 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
1fc60 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
1fc70 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
1fc80 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
1fc90 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
1fca0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
1fcb0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
1fcc0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
1fcd0 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
1fce0 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
1fcf0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
1fd00 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
1fd10 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
1fd20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
1fd30 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
1fd40 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
1fd50 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
1fd60 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
1fd70 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
1fd80 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
1fd90 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
1fda0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
1fdb0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
1fdc0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
1fdd0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
1fde0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
1fdf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
1fe00 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
1fe10 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
1fe20 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
1fe30 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
1fe40 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
1fe50 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
1fe60 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
1fe70 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
1fe80 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
1fe90 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
1fea0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
1feb0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
1fec0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
1fed0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
1fee0 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
1fef0 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
1ff00 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
1ff10 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
1ff20 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
1ff30 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
1ff40 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
1ff50 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
1ff60 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
1ff70 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
1ff80 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
1ff90 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
1ffa0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
1ffb0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
1ffc0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
1ffd0 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
1ffe0 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
1fff0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
20000 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
20010 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
20020 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
20030 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
20040 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
20050 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20060 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
20070 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
20080 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
20090 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
200a0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
200b0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
200c0 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
200d0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
200e0 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
200f0 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
20100 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
20110 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
20120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20130 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
20140 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
20150 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
20160 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
20170 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
20180 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
20190 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
201a0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
201b0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
201c0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
201d0 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
201e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
201f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20200 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
20210 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
20220 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
20230 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
20240 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
20250 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
20260 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
20270 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
20280 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
20290 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
202a0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
202b0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
202c0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
202d0 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
202e0 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
202f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
20300 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
20310 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
20320 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
20330 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
20340 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
20350 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
20360 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
20370 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
20380 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
20390 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
203a0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
203b0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
203c0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
203d0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
203e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
203f0 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
20400 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
20410 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20420 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
20430 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
20440 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
20450 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
20460 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
20470 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
20480 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
20490 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
204a0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
204b0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
204c0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
204d0 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
204e0 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
204f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
20500 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
20510 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
20520 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
20530 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
20540 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
20550 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
20560 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
20570 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
20580 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
20590 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
205a0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
205b0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
205c0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
205d0 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
205e0 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
205f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20600 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
20610 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20620 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
20630 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20640 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
20650 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
20660 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
20670 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20680 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
20690 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
206a0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
206b0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
206c0 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
206d0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
206e0 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
206f0 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
20700 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20710 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
20720 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
20730 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
20740 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
20750 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
20760 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
20770 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
20780 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
20790 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
207a0 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
207b0 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
207c0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
207d0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
207e0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
207f0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
20800 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
20810 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
20820 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
20830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20840 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
20850 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
20860 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
20870 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
20880 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
20890 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
208a0 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
208b0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
208c0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
208d0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
208e0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
208f0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
20900 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
20910 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
20920 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
20930 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
20940 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
20950 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
20960 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
20970 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
20980 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
20990 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
209a0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
209b0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
209c0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
209d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
209e0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
209f0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
20a00 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
20a10 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
20a20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
20a30 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
20a40 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
20a50 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
20a60 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
20a70 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
20a80 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
20a90 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
20aa0 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61  ing for the data
20ab0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46  base will be UTF
20ac0 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33  -8 if.** sqlite3
20ad0 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
20ae0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
20af0 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54  called and.** UT
20b00 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
20b10 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66  ve byte order if
20b20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20b30 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  ) is used..**.**
20b40 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
20b50 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
20b60 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65  when it is opene
20b70 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20  d, resources.** 
20b80 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
20b90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
20ba0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
20bb0 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61   should be relea
20bc0 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e  sed by.** passin
20bd0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
20be0 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69  _close()] when i
20bf0 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72  t is no longer r
20c00 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  equired..**.** T
20c10 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  he sqlite3_open_
20c20 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
20c30 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
20c40 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65  3_open().** exce
20c50 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70  pt that it accep
20c60 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  ts two additiona
20c70 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72  l parameters for
20c80 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74   additional cont
20c90 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  rol.** over the 
20ca0 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e  new database con
20cb0 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20  nection.  ^(The 
20cc0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
20cd0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
20ce0 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65  en_v2() can take
20cf0 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66   one of.** the f
20d00 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76  ollowing three v
20d10 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c  alues, optionall
20d20 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
20d30 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
20d40 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
20d50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
20d60 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f  MUTEX], [SQLITE_
20d70 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
20d80 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
20d90 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
20da0 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  , and/or [SQLITE
20db0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73  _OPEN_URI] flags
20dc0 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
20dd0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
20de0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
20df0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20e00 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20e10 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
20e20 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
20e30 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
20e40 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
20e50 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
20e60 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
20e70 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20e80 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
20e90 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20ea0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20eb0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20ec0 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
20ed0 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
20ee0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
20ef0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
20f00 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
20f10 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
20f20 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
20f30 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
20f40 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
20f50 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
20f60 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
20f70 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
20f80 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
20f90 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
20fa0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
20fb0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
20fc0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
20fd0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
20fe0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
20ff0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
21000 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64  eated if.** it d
21010 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20  oes not already 
21020 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74  exist. This is t
21030 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74  he behavior that
21040 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
21050 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
21060 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
21070 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e  3_open16().</dd>
21080 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  )^.** </dl>.**.*
21090 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72  * If the 3rd par
210a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
210b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e  3_open_v2() is n
210c0 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  ot one of the.**
210d0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68   combinations sh
210e0 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e  own above option
210f0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
21100 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c  th other.** [SQL
21110 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21120 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  Y | SQLITE_OPEN_
21130 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20  * bits].** then 
21140 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21150 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
21160 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
21170 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66  _OPEN_NOMUTEX] f
21180 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e  lag is set, then
21190 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
211a0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e  nnection.** open
211b0 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74  s in the multi-t
211c0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
211d0 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61   mode] as long a
211e0 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72  s the single-thr
211f0 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20  ead.** mode has 
21200 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20  not been set at 
21210 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
21220 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66  start-time.  ^If
21230 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
21240 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20  OPEN_FULLMUTEX] 
21250 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e  flag is set then
21260 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21270 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a  nnection opens.*
21280 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69  * in the seriali
21290 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
212a0 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67  ode] unless sing
212b0 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a  le-thread was.**
212c0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65   previously sele
212d0 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d  cted at compile-
212e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
212f0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  me..** ^The [SQL
21300 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21310 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
21320 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
21330 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a  onnection to be.
21340 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75  ** eligible to u
21350 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  se [shared cache
21360 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65   mode], regardle
21370 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21380 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63   not shared.** c
21390 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20  ache is enabled 
213a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  using [sqlite3_e
213b0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
213c0 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20  he()].  ^The.** 
213d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
213e0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20  VATECACHE] flag 
213f0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
21400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21410 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69  o not.** partici
21420 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20  pate in [shared 
21430 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e  cache mode] even
21440 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65   if it is enable
21450 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
21460 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
21470 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
21480 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
21490 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
214a0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
214b0 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
214c0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
214d0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
214e0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
214f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
21500 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
21510 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
21520 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
21530 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
21540 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
21550 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
21560 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  is used..**.** ^
21570 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
21580 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
21590 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
215a0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
215b0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
215c0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
215d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
215e0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
215f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
21600 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
21610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21620 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
21630 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
21640 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
21650 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
21660 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
21670 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
21680 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
21690 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
216a0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
216b0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
216c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
216d0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
216e0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
216f0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
21700 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
21710 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
21720 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
21730 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
21740 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
21750 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
21760 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
21770 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
21780 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
21790 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
217a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
217b0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
217c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
217d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
217e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
217f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
21800 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21810 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
21820 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69  ..**.** [[URI fi
21830 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74  lenames in sqlit
21840 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e  e3_open()]] <h3>
21850 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68  URI Filenames</h
21860 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52  3>.**.** ^If [UR
21870 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65  I filename] inte
21880 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
21890 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66  abled, and the f
218a0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
218b0 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20  .** begins with 
218c0 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68  "file:", then th
218d0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e  e filename is in
218e0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55  terpreted as a U
218f0 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65  RI. ^URI.** file
21900 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
21910 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ion is enabled i
21920 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21930 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a  EN_URI] flag is.
21940 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f  ** set in the fo
21950 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
21960 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21970 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73  (), or if it has
21980 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64  .** been enabled
21990 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20   globally using 
219a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
219b0 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77  IG_URI] option w
219c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ith the.** [sqli
219d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65  te3_config()] me
219e0 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b  thod or by the [
219f0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
21a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
21a10 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51  ion..** As of SQ
21a20 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
21a30 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .7, URI filename
21a40 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
21a50 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a  is turned off.**
21a60 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74   by default, but
21a70 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
21a80 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
21a90 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65   enable URI file
21aa0 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  name.** interpre
21ab0 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c  tation by defaul
21ac0 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69  t.  See "[URI fi
21ad0 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64  lenames]" for ad
21ae0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
21af0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55  rmation..**.** U
21b00 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  RI filenames are
21b10 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e   parsed accordin
21b20 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e  g to RFC 3986. ^
21b30 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61  If the URI conta
21b40 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72  ins an.** author
21b50 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73  ity, then it mus
21b60 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65  t be either an e
21b70 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74  mpty string or t
21b80 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c  he string .** "l
21b90 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74  ocalhost". ^If t
21ba0 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20  he authority is 
21bb0 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72  not an empty str
21bc0 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73  ing or "localhos
21bd0 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72  t", an .** error
21be0 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20   is returned to 
21bf0 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65  the caller. ^The
21c00 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e   fragment compon
21c10 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66  ent of a URI, if
21c20 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73   .** present, is
21c30 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
21c40 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
21c50 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20   path component 
21c60 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
21c70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69  e name of the di
21c80 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68  sk file.** which
21c90 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61   contains the da
21ca0 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20  tabase. ^If the 
21cb0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
21cc0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
21cd0 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  , .** then it is
21ce0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
21cf0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
21d00 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64  . ^If the path d
21d10 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a  oes not begin .*
21d20 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65  * with a '/' (me
21d30 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61  aning that the a
21d40 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e  uthority section
21d50 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
21d60 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65   the URI).** the
21d70 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e  n the path is in
21d80 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72  terpreted as a r
21d90 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a  elative path. .*
21da0 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74  * ^On windows, t
21db0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
21dc0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
21dd0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
21de0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
21df0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
21e00 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
21e10 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
21e20 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
21e30 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
21e40 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
21e50 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
21e60 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
21e70 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
21e80 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
21e90 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
21ea0 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
21eb0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
21ec0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
21ed0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
21ee0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
21ef0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
21f00 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f     <li> <b>vfs</
21f10 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70  b>: ^The "vfs" p
21f20 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
21f30 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20  used to specify 
21f40 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20  the name of.**  
21f50 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20     a VFS object 
21f60 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68  that provides th
21f70 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21f80 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21f90 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20  t should.**     
21fa0 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73  be used to acces
21fb0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
21fc0 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66  ile on disk. ^If
21fd0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
21fe0 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e  set to.**     an
21ff0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68   empty string th
22000 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62  e default VFS ob
22010 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53  ject is used. ^S
22020 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
22030 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20  nown.**     VFS 
22040 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66  is an error. ^If
22050 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22060 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
22070 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73  he vfs option is
22080 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c  .**     present,
22090 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70   then the VFS sp
220a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
220b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63  ption takes prec
220c0 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20  edence over.**  
220d0 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73     the value pas
220e0 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74  sed as the fourt
220f0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22100 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22110 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
22120 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68  b>mode</b>: ^(Th
22130 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
22140 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
22150 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22  ither "ro", "rw"
22160 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20  ,.**     "rwc", 
22170 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74  or "memory". Att
22180 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
22190 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
221a0 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61  alue is.**     a
221b0 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
221c0 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
221d0 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
221e0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
221f0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
22200 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
22210 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
22220 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22230 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
22240 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
22250 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
22260 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
22270 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22280 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
22290 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a  ion is set to .*
222a0 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e  *     "rw", then
222b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
222c0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
222d0 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20  -write (but not 
222e0 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20  create) .**     
222f0 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51  access, as if SQ
22300 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22310 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c  ITE (but not SQL
22320 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29  ITE_OPEN_CREATE)
22330 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65   had .**     bee
22340 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72  n set. ^Value "r
22350 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  wc" is equivalen
22360 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74  t to setting bot
22370 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  h .**     SQLITE
22380 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
22390 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  and SQLITE_OPEN_
223a0 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65  CREATE.  ^If the
223b0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a   mode option is.
223c0 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d  **     set to "m
223d0 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75  emory" then a pu
223e0 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  re [in-memory da
223f0 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76  tabase] that nev
22400 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20  er reads.**     
22410 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64  or writes from d
22420 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74  isk is used. ^It
22430 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20   is an error to 
22440 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20  specify a value 
22450 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d  for.**     the m
22460 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  ode parameter th
22470 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72  at is less restr
22480 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74  ictive than that
22490 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
224a0 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70       the flags p
224b0 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69  assed in the thi
224c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
224d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
224e0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
224f0 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
22500 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
22510 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
22520 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
22530 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
22540 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
22550 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
22560 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
22570 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
22580 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
22590 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
225a0 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
225b0 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
225c0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
225d0 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
225e0 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
225f0 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
22600 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
22610 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22620 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
22630 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
22640 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
22650 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22660 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
22670 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
22680 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
22690 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
226a0 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
226b0 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
226c0 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73   behavior reques
226d0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
226e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
226f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
22700 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
22710 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
22720 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70  **.**  <li> <b>p
22730 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73  sow</b>: ^The ps
22740 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  ow parameter may
22750 20 62 65 20 22 74 72 75 65 22 20 28 6f 72 20 22   be "true" (or "
22760 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f 72 0a  on" or "yes" or.
22770 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72 20 22  **     "1") or "
22780 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66 66 22  false" (or "off"
22790 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30 22 29   or "no" or "0")
227a0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
227b0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
227c0 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
227d0 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
227e0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
227f0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
22800 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
22810 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
22820 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
22830 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20 71 75  s.  ^The psow qu
22840 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
22850 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  eter only works 
22860 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  for the built-in
22870 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64 6f 77   unix and Window
22880 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a 20 20  s VFSes..**.**  
22890 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f  <li> <b>nolock</
228a0 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20  b>: ^The nolock 
228b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
228c0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72  oolean query par
228d0 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68  ameter.**     wh
228e0 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62  ich if set disab
228f0 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67  les file locking
22900 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75   in rollback jou
22910 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69  rnal modes.  Thi
22920 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66  s.**     is usef
22930 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67  ul for accessing
22940 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61   a database on a
22950 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74   filesystem that
22960 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20   does not.**    
22970 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67   support locking
22980 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74  .  Caution:  Dat
22990 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
229a0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
229b0 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d   two.**     or m
229c0 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72  ore processes wr
229d0 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ite to the same 
229e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79  database and any
229f0 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a   one of those.**
22a00 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75       processes u
22a10 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a  ses nolock=1..**
22a20 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d  .**  <li> <b>imm
22a30 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65  utable</b>: ^The
22a40 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d   immutable param
22a50 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
22a60 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  n query.**     p
22a70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e  arameter that in
22a80 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
22a90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
22aa0 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20  s stored on.**  
22ab0 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64     read-only med
22ac0 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74  ia.  ^When immut
22ad0 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c  able is set, SQL
22ae0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
22af0 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
22b00 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74  base file cannot
22b10 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65   be changed, eve
22b20 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77  n by a process w
22b30 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20  ith higher.**   
22b40 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64    privilege, and
22b50 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   so the database
22b60 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d   is opened read-
22b70 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63  only and all loc
22b80 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20  king.**     and 
22b90 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e  change detection
22ba0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43   is disabled.  C
22bb0 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20  aution: Setting 
22bc0 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a  the immutable.**
22bd0 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e       property on
22be0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
22bf0 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61   that does in fa
22c00 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65  ct change can re
22c10 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69  sult.**     in i
22c20 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72  ncorrect query r
22c30 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53  esults and/or [S
22c40 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65  QLITE_CORRUPT] e
22c50 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65  rrors..**     Se
22c60 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
22c70 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
22c80 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c  ..**       .** <
22c90 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63  /ul>.**.** ^Spec
22ca0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
22cb0 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  n parameter in t
22cc0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
22cd0 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e  nt of a URI is n
22ce0 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20  ot an.** error. 
22cf0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22d00 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22d10 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69   understand addi
22d20 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20  tional query.** 
22d30 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65  parameters.  See
22d40 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74   "[query paramet
22d50 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c  ers with special
22d60 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69   meaning to SQLi
22d70 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69  te]" for.** addi
22d80 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
22d90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  on..**.** [[URI 
22da0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22db0 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65  s]] <h3>URI file
22dc0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68  name examples</h
22dd0 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  3>.**.** <table 
22de0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
22df0 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
22e00 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
22e10 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
22e20 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
22e30 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
22e40 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
22e50 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22e60 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
22e70 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
22e80 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
22e90 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
22ea0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
22eb0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
22ec0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
22ed0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
22ee0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
22ef0 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
22f00 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
22f10 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
22f20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
22f30 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
22f40 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
22f50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22f60 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
22f70 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22f80 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
22f90 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
22fa0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
22fb0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
22fc0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
22fd0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
22fe0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
22ff0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23000 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
23010 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
23020 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
23030 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
23040 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
23050 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
23060 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
23070 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
23080 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
23090 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
230a0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
230b0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
230c0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
230d0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
230e0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
230f0 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
23100 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
23110 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
23120 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
23130 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
23140 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
23150 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
23160 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23170 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
23180 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
23190 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
231a0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
231b0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
231c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
231d0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
231e0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
231f0 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
23200 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
23210 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
23220 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23230 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23240 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64  ta.db?vfs=unix-d
23250 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20  otfile <td>.**  
23260 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
23270 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
23280 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20  ta.db". Use the 
23290 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69  special VFS "uni
232a0 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20  x-dotfile".**   
232b0 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73         that uses
232c0 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c   dot-files in pl
232d0 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76  ace of posix adv
232e0 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a  isory locking..*
232f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23300 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
23310 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
23320 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
23330 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
23340 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
23350 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
23360 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
23370 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
23380 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
23390 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
233a0 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
233b0 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
233c0 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
233d0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
233e0 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
233f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23400 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
23410 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
23420 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
23430 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
23440 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
23450 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
23460 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
23470 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
23480 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
23490 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
234a0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
234b0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
234c0 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
234d0 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
234e0 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
234f0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
23500 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
23510 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
23520 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
23530 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
23540 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
23550 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
23560 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
23570 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
23580 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
23590 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
235a0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
235b0 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
235c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
235d0 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
235e0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
235f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23600 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
23610 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
23620 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
23630 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
23640 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
23650 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
23660 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
23670 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
23680 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
23690 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
236a0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
236b0 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
236c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
236d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
236e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ()..**.** <b>Not
236f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e  e to Windows Run
23700 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20  time users:</b> 
23710 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64   The temporary d
23720 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65  irectory must be
23730 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f   set.** prior to
23740 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33   calling sqlite3
23750 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
23760 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f  e3_open_v2().  O
23770 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75  therwise, variou
23780 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68  s.** features th
23790 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75  at require the u
237a0 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20  se of temporary 
237b0 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a  files may fail..
237c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
237d0 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  [sqlite3_temp_di
237e0 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20  rectory].*/.int 
237f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
23800 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23810 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23820 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23830 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23840 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
23850 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23860 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
23870 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
23880 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
23890 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
238a0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
238b0 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
238c0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
238d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
238e0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
238f0 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  le */.);.int sql
23900 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
23910 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
23920 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
23930 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
23940 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
23950 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
23960 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
23970 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
23980 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
23990 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
239a0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
239b0 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
239c0 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
239d0 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
239e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
239f0 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
23a00 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
23a10 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
23a20 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
23a30 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
23a40 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
23a50 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
23a60 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
23a70 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
23a80 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
23a90 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
23aa0 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
23ab0 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
23ac0 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
23ad0 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
23ae0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
23af0 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
23b00 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
23b10 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
23b20 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
23b30 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
23b40 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
23b50 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
23b60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
23b70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
23b80 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
23b90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23ba0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
23bb0 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
23bc0 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
23bd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23be0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
23bf0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
23c00 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
23c10 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
23c20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
23c30 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
23c40 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
23c50 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
23c60 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
23c70 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
23c80 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
23c90 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
23ca0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
23cb0 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
23cc0 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
23cd0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23ce0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23cf0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
23d00 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23d10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23d20 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
23d30 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
23d40 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
23d50 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
23d60 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
23d70 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
23d80 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
23d90 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
23da0 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
23db0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
23dc0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
23dd0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
23de0 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
23df0 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
23e00 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
23e10 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
23e20 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
23e30 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
23e40 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
23e50 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
23e60 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
23e70 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23e80 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23e90 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
23ea0 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
23eb0 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
23ec0 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
23ed0 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
23ee0 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
23ef0 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
23f00 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23f10 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
23f20 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
23f30 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
23f40 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
23f50 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
23f60 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
23f70 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
23f80 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
23f90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23fa0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
23fb0 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
23fc0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
23fd0 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
23fe0 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
23ff0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
24000 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
24010 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
24020 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
24030 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
24040 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
24050 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
24060 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
24070 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
24080 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
24090 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
240a0 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
240b0 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
240c0 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
240d0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
240e0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
240f0 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
24100 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
24110 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
24120 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
24130 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
24140 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
24150 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
24160 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
24170 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
24180 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
24190 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
241a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
241b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
241c0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
241d0 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
241e0 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  rable..*/.const 
241f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
24200 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
24210 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
24220 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24230 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69  Param);.int sqli
24240 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
24250 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24260 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
24270 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
24280 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ult);.sqlite3_in
24290 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
242a0 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
242b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
242c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
242d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
242e0 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
242f0 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
24300 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
24310 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
24320 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
24330 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
24340 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
24350 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24360 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
24370 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
24380 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
24390 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
243a0 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
243b0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
243c0 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
243d0 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
243e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
243f0 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
24400 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
24410 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
24420 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
24430 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
24440 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24450 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24460 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24470 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24480 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24490 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
244a0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
244b0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
244c0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
244d0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
244e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
244f0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24500 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24510 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24520 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24530 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24540 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24550 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24560 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24570 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24580 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24590 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
245a0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
245b0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
245c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
245d0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
245e0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
245f0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24600 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24610 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24620 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24630 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24640 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24650 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24660 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24670 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24680 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24690 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
246a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
246b0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
246c0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
246d0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
246e0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
246f0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
24700 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
24710 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
24720 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
24730 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
24740 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
24750 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
24760 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
24770 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
24780 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
24790 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
247a0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
247b0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
247c0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
247d0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
247e0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
247f0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
24800 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
24810 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
24820 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
24830 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
24840 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
24850 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
24860 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
24870 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
24880 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
24890 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
248a0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
248b0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
248c0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
248d0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
248e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
248f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
24900 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
24910 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
24920 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
24930 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
24940 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
24950 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
24960 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24970 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
24980 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24990 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
249a0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
249b0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
249c0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
249d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
249e0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
249f0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
24a00 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
24a10 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
24a20 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
24a30 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
24a40 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
24a50 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
24a60 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
24a70 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
24a80 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
24a90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
24aa0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
24ab0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
24ac0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
24ad0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
24ae0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24af0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
24b00 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
24b10 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
24b20 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
24b30 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
24b40 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
24b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
24b60 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
24b70 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
24b80 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
24b90 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
24ba0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
24bb0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
24bc0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
24bd0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
24be0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
24bf0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
24c00 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
24c10 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
24c20 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
24c30 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
24c40 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
24c50 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
24c60 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
24c70 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
24c80 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
24c90 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
24ca0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
24cb0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
24cc0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
24cd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
24ce0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
24cf0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
24d00 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
24d10 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
24d20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
24d30 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
24d40 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
24d50 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
24d60 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
24d70 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
24d80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24d90 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
24da0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
24db0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
24dc0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
24dd0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
24de0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
24df0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
24e00 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
24e10 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
24e20 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
24e30 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
24e40 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
24e50 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
24e60 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
24e70 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
24e80 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
24e90 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
24ea0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
24eb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
24ec0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
24ed0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
24ee0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
24ef0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
24f00 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
24f10 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
24f20 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
24f30 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
24f40 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
24f50 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
24f60 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
24f70 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
24f80 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
24f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24fa0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
24fb0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
24fc0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
24fd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
24fe0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
24ff0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25000 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
25010 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
25020 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
25030 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
25040 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25050 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
25060 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
25070 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
25080 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
25090 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
250a0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
250b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
250c0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
250d0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
250e0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
250f0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25100 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
25110 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
25120 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
25130 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
25140 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25150 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
25160 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
25170 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
25180 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
25190 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
251a0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
251b0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
251c0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
251d0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
251e0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
251f0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25200 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
25210 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
25220 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
25230 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25240 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
25250 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
25260 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
25270 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
25280 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25290 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
252a0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
252b0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
252c0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
252d0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
252e0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
252f0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25300 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25310 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25320 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25330 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25340 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25350 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25360 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
25370 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
25380 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
25390 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
253a0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
253b0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
253c0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
253d0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
253e0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
253f0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25400 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25410 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25420 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25430 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25440 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25450 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25460 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25470 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25480 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25490 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
254a0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
254b0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
254c0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
254d0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
254e0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
254f0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25500 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25510 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25520 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25530 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25540 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25550 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25560 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25570 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25580 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25590 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
255a0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
255b0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
255c0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
255d0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
255e0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
255f0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25600 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25610 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25620 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25630 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25640 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25650 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25660 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25670 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25680 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25690 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
256a0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
256b0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
256c0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
256d0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
256e0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
256f0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
25700 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
25710 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
25720 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
25730 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
25740 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
25750 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
25760 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
25770 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
25780 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
25790 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
257a0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
257b0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
257c0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
257d0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
257e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
257f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
25800 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
25810 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
25820 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
25830 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
25840 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
25850 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25860 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
25870 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
25880 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
25890 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
258a0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
258b0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
258c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
258d0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
258e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
258f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25900 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25910 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
25920 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
25930 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
25940 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25950 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
25960 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25970 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
25980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25990 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
259a0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
259b0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
259c0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
259d0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
259e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
259f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
25a00 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
25a10 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
25a20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
25a30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
25a40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25a50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
25a60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
25a70 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25a80 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25a90 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
25aa0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
25ab0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
25ac0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25ad0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25ae0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
25af0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
25b00 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
25b10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25b20 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
25b30 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
25b40 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
25b50 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
25b60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
25b70 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
25b80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
25b90 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
25ba0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
25bb0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
25bc0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
25bd0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
25be0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
25bf0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
25c00 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
25c10 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
25c20 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
25c30 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
25c40 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
25c50 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
25c60 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
25c70 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
25c80 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
25c90 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
25ca0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25cb0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
25cc0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25cd0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
25ce0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
25cf0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
25d00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25d10 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
25d20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25d30 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
25d40 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25d50 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
25d60 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
25d70 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
25d80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
25d90 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25da0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
25db0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25dc0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
25dd0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
25de0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25df0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
25e00 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
25e10 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
25e20 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
25e30 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
25e40 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25e50 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
25e60 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
25e70 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
25e80 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
25e90 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25ea0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
25eb0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
25ec0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
25ed0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
25ee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25ef0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
25f00 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25f10 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
25f20 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25f30 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
25f40 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
25f50 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
25f60 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
25f70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
25f80 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
25f90 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
25fa0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25fb0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
25fc0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
25fd0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25fe0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
25ff0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
26000 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26010 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
26020 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
26030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26040 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26050 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
26060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26070 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
26080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
26090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
260a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
260b0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
260c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
260d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
260e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
260f0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
26100 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26110 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
26120 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
26130 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26140 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
26150 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
26160 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
26170 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
26180 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
26190 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
261a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
261b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
261c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
261d0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
261e0 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
261f0 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
26200 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
26210 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
26220 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
26230 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
26240 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
26250 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
26260 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
26270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26280 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
26290 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
262a0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
262b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
262c0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
262d0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
262e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
262f0 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
26300 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
26310 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
26320 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
26330 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
26340 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
26350 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
26360 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
26370 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
26380 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
26390 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
263a0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
263b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
263c0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
263d0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
263e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
263f0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26400 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
26410 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
26420 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
26430 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
26440 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
26450 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
26460 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
26470 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
26480 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
26490 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
264a0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
264b0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
264c0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
264d0 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
264e0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
264f0 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
26500 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
26510 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
26520 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
26530 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
26540 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
26550 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
26560 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
26570 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
26580 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
26590 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
265a0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
265b0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
265c0 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
265d0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
265e0 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
265f0 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
26600 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
26610 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
26620 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
26630 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
26640 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
26650 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
26660 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
26670 73 20 61 73 20 74 68 69 73 20 73 61 76 65 73 20  s as this saves 
26680 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69  SQLite from havi
26690 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20  ng to.** make a 
266a0 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75  copy of the inpu
266b0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  t string..**.** 
266c0 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
266d0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
266e0 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
266f0 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
26700 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
26710 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
26720 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
26730 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
26740 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
26750 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
26760 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
26770 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
26780 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
26790 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
267a0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
267b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
267c0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
267d0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
267e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
267f0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
26800 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
26810 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
26820 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
26830 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
26840 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
26850 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
26860 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
26870 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
26880 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
26890 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
268a0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
268b0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
268c0 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
268d0 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
268e0 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
268f0 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
26900 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
26910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
26920 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
26930 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
26940 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
26950 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
26960 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
26970 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
26980 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
26990 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
269a0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
269b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
269c0 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
269d0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
269e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
269f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26a00 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
26a10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26a20 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
26a30 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
26a40 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
26a50 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
26a60 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
26a70 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
26a80 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
26a90 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
26aa0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
26ab0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
26ac0 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
26ad0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
26ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26af0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
26b00 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
26b10 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
26b20 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
26b30 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
26b40 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
26b50 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
26b60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26b70 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
26b80 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
26b90 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
26ba0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
26bb0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
26bc0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
26bd0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
26be0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
26bf0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
26c00 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
26c10 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
26c20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
26c30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
26c40 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
26c50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
26c60 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
26c70 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
26c80 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
26c90 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
26ca0 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
26cb0 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
26cc0 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
26cd0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
26ce0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
26cf0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
26d00 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
26d10 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
26d20 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
26d30 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
26d40 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
26d50 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
26d60 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
26d70 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
26d80 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
26d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
26da0 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
26db0 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
26dc0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
26dd0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
26de0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
26df0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
26e00 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
26e10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
26e20 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
26e30 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
26e40 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
26e50 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
26e60 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
26e70 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
26e80 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
26e90 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
26ea0 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
26eb0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
26ec0 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
26ed0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26ee0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
26ef0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
26f00 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
26f10 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
26f20 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
26f30 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
26f40 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
26f50 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
26f60 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
26f70 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
26f80 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
26f90 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
26fa0 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
26fb0 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
26fc0 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
26fd0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
26fe0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
26ff0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
27000 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
27010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27020 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
27030 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
27040 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
27050 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
27060 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
27070 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
27080 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
27090 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
270a0 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
270b0 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
270c0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
270d0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
270e0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
270f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
27100 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
27110 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
27120 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
27130 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
27140 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
27150 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
27160 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
27170 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
27180 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
27190 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
271a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
271b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
271c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
271d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
271e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
271f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27200 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27210 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27220 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27230 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
27240 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
27250 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
27260 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
27270 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
27280 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
27290 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
272a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
272b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
272c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
272d0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
272e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
272f0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
27300 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27310 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27330 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
27340 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
27350 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
27360 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
27370 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
27380 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
27390 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
273a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
273b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
273c0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
273d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
273e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
273f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
27400 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
27410 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
27420 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27430 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
27440 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27450 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
27460 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
27470 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
27480 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
27490 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
274a0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
274b0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
274c0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
274d0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
274e0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
274f0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27500 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
27510 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27520 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27530 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
27540 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
27550 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
27560 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
27570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
27580 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
27590 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
275a0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
275b0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
275c0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
275d0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
275e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
275f0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27600 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27610 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27620 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27630 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27640 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
27650 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
27660 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
27670 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27680 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
276a0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
276b0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20  ement SQL.**.** 
276c0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
276d0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
276e0 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20  etrieve a saved 
276f0 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67  copy of the orig
27700 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74  inal.** SQL text
27710 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
27720 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
27730 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73  ement] if that s
27740 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20  tatement was.** 
27750 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65  compiled using e
27760 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
27770 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27780 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27790 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  16_v2()]..*/.con
277a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
277b0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
277c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
277d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
277e0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
277f0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
27800 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
27810 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27820 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
27830 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27840 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
27850 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
27860 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
27870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
27880 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
27890 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
278a0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
278b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
278c0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
278d0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
278e0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
278f0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
27900 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
27910 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
27920 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
27930 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
27940 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
27950 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
27960 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
27970 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
27980 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
27990 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
279a0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
279b0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
279c0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
279d0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
279e0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
279f0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
27a00 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
27a10 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
27a20 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
27a30 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
27a40 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
27a50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
27a60 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
27a70 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27a80 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
27a90 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
27aa0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
27ab0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
27ac0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
27ad0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
27ae0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
27af0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
27b00 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
27b10 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
27b20 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
27b30 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
27b40 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
27b50 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
27b60 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
27b70 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
27b80 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
27b90 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
27ba0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
27bb0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
27bc0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
27bd0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
27be0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
27bf0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
27c00 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
27c10 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
27c20 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
27c30 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
27c40 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
27c50 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
27c60 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
27c70 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
27c80 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
27c90 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
27ca0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
27cb0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
27cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
27cd0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
27ce0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
27cf0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
27d00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
27d10 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
27d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27d30 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
27d40 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
27d60 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
27d70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
27d80 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
27d90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27da0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
27db0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
27dc0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
27dd0 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
27de0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
27df0 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
27e00 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
27e10 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27e20 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
27e30 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
27e40 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
27e50 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
27e60 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
27e70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
27e80 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
27e90 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
27ea0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27eb0 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
27ec0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
27ed0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
27ee0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
27ef0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
27f00 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
27f10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27f20 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
27f30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
27f40 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
27f50 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
27f60 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
27f70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
27f80 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
27f90 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
27fa0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
27fb0 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
27fc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27fd0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
27fe0 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
27ff0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
28000 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
28010 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
28020 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
28030 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
28040 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
28050 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
28060 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
28070 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
28080 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
28090 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
280a0 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  en..*/.int sqlit
280b0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
280c0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
280d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
280e0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
280f0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
28100 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
28110 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28120 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
28130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
28140 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
28150 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
28160 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
28170 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
28180 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
28190 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
281a0 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
281b0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
281c0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
281d0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
281e0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
281f0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
28200 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
28210 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
28220 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
28230 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
28240 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
28250 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
28260 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
28270 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
28280 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
28290 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
282a0 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
282b0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
282c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
282d0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
282e0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
282f0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
28300 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
28310 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
28320 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
28330 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
28340 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
28350 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
28360 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
28370 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
28380 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
28390 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
283a0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
283b0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
283c0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
283d0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
283e0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
283f0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
28400 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
28410 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
28420 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
28430 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28440 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
28450 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
28460 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
28470 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
28480 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
28490 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
284a0 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
284b0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
284c0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
284d0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
284e0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
284f0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
28500 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
28510 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
28520 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
28530 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
28540 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
28550 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
28560 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
28570 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
28580 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
28590 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
285a0 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
285b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
285c0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
285d0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
285e0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
285f0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
28600 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
28610 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
28620 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
28630 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
28640 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
28650 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
28660 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
28670 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
28680 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28690 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
286a0 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
286b0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
286c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
286d0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
286e0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
286f0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
28700 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
28710 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
28720 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
28730 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
28740 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
28750 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28760 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
28770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
28780 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
28790 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
287a0 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
287b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
287c0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
287d0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
287e0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
287f0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
28800 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
28810 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
28820 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
28830 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
28840 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
28850 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
28860 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
28870 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
28880 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
28890 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
288a0 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
288b0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
288c0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
288d0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
288e0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
288f0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
28900 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
28910 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
28920 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
28930 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
28940 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
28950 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
28960 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
28970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
28980 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28990 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
289a0 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
289b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
289c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
289d0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
289e0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
289f0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
28a00 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
28a10 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
28a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
28a30 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
28a40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
28a50 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
28a60 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
28a70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
28a80 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
28a90 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
28aa0 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
28ab0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
28ac0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
28ad0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
28ae0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
28af0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
28b00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
28b10 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
28b20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
28b30 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
28b40 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
28b50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
28b60 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
28b70 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
28b80 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
28b90 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
28ba0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
28bb0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
28bc0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
28bd0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
28be0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
28bf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
28c00 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
28c10 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
28c20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
28c30 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
28c40 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
28c50 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
28c60 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
28c70 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
28c80 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
28c90 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
28ca0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
28cb0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
28cc0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
28cd0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
28ce0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
28cf0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
28d00 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
28d10 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
28d20 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
28d30 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
28d40 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
28d50 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
28d60 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
28d70 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
28d80 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
28d90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
28da0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
28db0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28dc0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
28dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
28de0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
28df0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
28e00 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
28e10 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
28e20 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
28e30 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
28e40 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
28e50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
28e60 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
28e70 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
28e80 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
28e90 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
28ea0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
28eb0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
28ec0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
28ed0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
28ee0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
28ef0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
28f00 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
28f10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
28f20 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
28f30 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
28f40 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
28f50 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
28f60 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
28f70 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
28f80 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
28f90 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
28fa0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
28fb0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
28fc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
28fd0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
28fe0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
28ff0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
29000 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
29010 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
29020 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
29030 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
29040 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
29050 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
29060 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
29070 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
29080 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
29090 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
290a0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
290b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
290c0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
290d0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
290e0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
290f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
29100 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29120 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
29130 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
29140 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
29150 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
29160 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
29170 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29180 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
29190 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
291a0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
291b0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
291c0 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
291d0 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
291e0 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
291f0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
29200 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
29210 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
29220 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
29230 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
29240 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
29250 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
29260 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
29270 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
29280 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
29290 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
292a0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
292b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
292c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
292d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
292e0 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
292f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
29300 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
29310 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
29320 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
29330 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
29340 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
29350 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
29360 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
29370 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29380 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
29390 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
293a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
293b0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
293c0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
293d0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
293e0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
293f0 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
29400 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
29410 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
29420 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
29430 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
29440 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
29450 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
29460 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
29470 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
29480 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
29490 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
294a0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
294b0 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
294c0 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
294d0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
294e0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
294f0 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
29500 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
29510 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
29520 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
29530 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
29540 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
29550 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
29560 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
29570 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
29580 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
29590 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
295a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
295b0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
295c0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
295d0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
295e0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
295f0 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
29600 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
29610 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
29620 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
29630 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
29640 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
29650 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
29660 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
29670 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
29680 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
29690 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
296a0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
296b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
296c0 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
296d0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
296e0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
296f0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29700 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
29710 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
29720 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
29730 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
29740 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
29750 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
29760 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
29770 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
29780 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
29790 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
297a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
297b0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
297c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
297d0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
297e0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
297f0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
29800 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
29810 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
29820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29830 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
29840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29850 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
29860 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
29870 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
29880 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
29890 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
298a0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
298b0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
298c0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
298d0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
298e0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
298f0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
29900 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
29910 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
29920 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
29930 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
29940 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
29950 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
29960 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
29970 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
29980 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
29990 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
299a0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
299b0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
299c0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
299d0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
299e0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
299f0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
29a00 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
29a10 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
29a20 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
29a30 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
29a40 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
29a50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29a60 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
29a70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29a80 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
29a90 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
29aa0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
29ab0 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
29ac0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29ad0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
29ae0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
29af0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
29b00 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
29b10 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
29b20 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
29b30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29b40 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
29b50 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
29b60 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
29b70 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
29b80 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
29b90 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
29ba0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
29bb0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
29bc0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
29bd0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
29be0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
29bf0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
29c00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29c10 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
29c20 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
29c30 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
29c40 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
29c50 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
29c60 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
29c70 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
29c80 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
29c90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
29ca0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
29cb0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
29cc0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
29cd0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
29ce0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
29cf0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
29d00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
29d10 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
29d20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
29d30 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
29d40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
29d50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29d60 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
29d70 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29d90 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
29da0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
29db0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29dc0 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65  ite3_bind_double
29dd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29de0 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e  int, double);.in
29df0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
29e00 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
29e10 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74  , int, int);.int
29e20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
29e30 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
29e40 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
29e50 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69  int64);.int sqli
29e60 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71  te3_bind_null(sq
29e70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29e80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29e90 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33  ind_text(sqlite3
29ea0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
29eb0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c  st char*, int n,
29ec0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
29ed0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29ee0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
29ef0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
29f00 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
29f10 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
29f20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29f30 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
29f40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
29f50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
29f60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29f70 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
29f80 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29f90 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
29fa0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
29fb0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
29fc0 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
29fd0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
29fe0 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
29ff0 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2a000 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2a010 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2a020 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2a030 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2a040 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2a050 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2a060 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2a070 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2a080 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2a090 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2a0a0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2a0b0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2a0c0 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2a0d0 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2a0e0 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2a0f0 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2a100 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2a110 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2a120 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2a130 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2a140 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2a150 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2a160 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2a170 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2a180 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2a190 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2a1a0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2a1b0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2a1c0 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2a1d0 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2a1e0 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2a1f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a200 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a210 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a220 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a230 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2a240 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2a250 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a260 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2a270 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a280 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a290 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2a2a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a2b0 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2a2c0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
2a2d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2a2e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2a2f0 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2a300 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2a310 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2a320 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2a330 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2a340 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2a350 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2a360 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2a370 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2a380 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2a390 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2a3a0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2a3b0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2a3c0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2a3d0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2a3e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2a3f0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2a400 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2a410 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2a420 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2a430 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2a440 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2a450 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2a460 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2a470 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2a480 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2a490 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2a4a0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2a4b0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2a4c0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2a4d0 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2a4e0 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2a4f0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2a500 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2a510 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2a520 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2a530 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2a540 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2a550 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2a560 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2a570 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2a580 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2a590 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2a5a0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2a5b0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2a5c0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2a5d0 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2a5e0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2a5f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2a600 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2a610 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a620 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2a630 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2a640 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2a650 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2a660 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a670 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2a680 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a690 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a6a0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2a6b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2a6c0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2a6d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a6e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2a6f0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2a700 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2a710 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
2a720 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2a730 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2a740 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2a750 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2a760 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2a770 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2a780 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2a790 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2a7a0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2a7b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a7c0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2a7d0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2a7e0 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2a7f0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2a800 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2a810 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2a820 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2a830 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2a840 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2a850 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2a860 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2a870 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2a880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a890 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2a8a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a8b0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a8c0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2a8d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a8e0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2a8f0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a900 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a910 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2a920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2a930 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2a940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2a950 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2a960 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a970 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2a980 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2a990 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  d Statement.**.*
2a9a0 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
2a9b0 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
2a9c0 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
2a9d0 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
2a9e0 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
2a9f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2aa00 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
2aa10 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2aa20 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
2aa30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
2aa40 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
2aa50 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
2aa60 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  L..*/.int sqlite
2aa70 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
2aa80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2aa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2aaa0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
2aab0 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
2aac0 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
2aad0 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
2aae0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2aaf0 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
2ab00 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
2ab10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ab20 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
2ab30 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
2ab40 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
2ab50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
2ab60 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
2ab70 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
2ab80 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
2ab90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2aba0 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
2abb0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2abc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2abd0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2abe0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2abf0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e  CAPI3REF: Column
2ac00 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75   Names In A Resu
2ac10 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  lt Set.**.** ^Th
2ac20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2ac30 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73  urn the name ass
2ac40 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69  igned to a parti
2ac50 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  cular column.** 
2ac60 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
2ac70 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2ac80 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65  statement.  ^The
2ac90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2aca0 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  name().** interf
2acb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2acc0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2acd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
2ace0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73   string.** and s
2acf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2ad00 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61  me16() returns a
2ad10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2ad20 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
2ad30 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2ad40 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
2ad50 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72  meter is the [pr
2ad60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ad70 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d  ].** that implem
2ad80 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54  ents the [SELECT
2ad90 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68  ] statement. ^Th
2ada0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2adb0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c  er is the.** col
2adc0 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68  umn number.  ^Th
2add0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
2ade0 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a  n is number 0..*
2adf0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  *.** ^The return
2ae00 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ed string pointe
2ae10 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  r is valid until
2ae20 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65   either the [pre
2ae30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ae40 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64  .** is destroyed
2ae50 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   by [sqlite3_fin
2ae60 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2ae70 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2ae80 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2ae90 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2aea0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2aeb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2aec0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2aed0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2aee0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63  until the next c
2aef0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2af00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20  3_column_name() 
2af10 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2af20 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68  n_name16() on th
2af30 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a  e same column..*
2af40 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  *.** ^If sqlite3
2af50 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20  _malloc() fails 
2af60 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65  during the proce
2af70 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20  ssing of either 
2af80 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20  routine.** (for 
2af90 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61  example during a
2afa0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d   conversion from
2afb0 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36   UTF-8 to UTF-16
2afc0 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  ) then a.** NULL
2afd0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2afe0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2aff0 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c   name of a resul
2b000 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20  t column is the 
2b010 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53  value of the "AS
2b020 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20  " clause for.** 
2b030 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20  that column, if 
2b040 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63  there is an AS c
2b050 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65  lause.  If there
2b060 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65   is no AS clause
2b070 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d  .** then the nam
2b080 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  e of the column 
2b090 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61  is unspecified a
2b0a0 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72  nd may change fr
2b0b0 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73  om.** one releas
2b0c0 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74  e of SQLite to t
2b0d0 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73  he next..*/.cons
2b0e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b0f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
2b100 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2b110 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2b130 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2b140 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2b150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2b160 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2b170 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2b180 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b190 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
2b1a0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
2b1b0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
2b1c0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
2b1d0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
2b1e0 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
2b1f0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
2b200 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
2b210 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2b220 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
2b230 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
2b240 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
2b250 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
2b260 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
2b270 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
2b280 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2b290 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
2b2a0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
2b2b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
2b2c0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
2b2d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2b2e0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
2b2f0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
2b300 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2b310 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
2b320 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
2b330 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
2b340 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
2b350 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b360 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
2b370 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
2b380 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2b390 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
2b3a0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
2b3b0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
2b3c0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
2b3d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2b3e0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
2b3f0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
2b400 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
2b410 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
2b420 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
2b430 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
2b440 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
2b450 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
2b460 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
2b470 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
2b480 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
2b490 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
2b4a0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
2b4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2b4c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2b4d0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
2b4e0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2b4f0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
2b500 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2b510 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2b520 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
2b530 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
2b540 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
2b550 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
2b560 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
2b570 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
2b580 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
2b590 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
2b5a0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
2b5b0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
2b5c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
2b5d0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
2b5e0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
2b5f0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
2b600 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
2b610 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
2b620 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
2b630 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
2b640 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
2b650 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
2b660 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
2b670 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
2b680 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2b690 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
2b6a0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
2b6b0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
2b6c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2b6d0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
2b6e0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
2b6f0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
2b700 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
2b710 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
2b720 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
2b730 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
2b740 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
2b750 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
2b760 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
2b770 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
2b780 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
2b790 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
2b7a0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
2b7b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
2b7c0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
2b7d0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
2b7e0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
2b7f0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
2b800 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
2b810 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
2b820 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
2b830 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
2b840 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2b850 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2b860 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
2b870 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
2b880 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
2b890 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
2b8a0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
2b8b0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
2b8c0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
2b8d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b8e0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
2b8f0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
2b900 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
2b910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2b920 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
2b930 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
2b940 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
2b950 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
2b960 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
2b970 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
2b980 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
2b990 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2b9a0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2b9b0 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  d..*/.const char
2b9c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b9d0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
2b9e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b9f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2ba00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2ba10 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
2ba20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2ba30 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2ba40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2ba50 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2ba60 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2ba70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ba80 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2ba90 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2baa0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
2bab0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2bac0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
2bad0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2bae0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2baf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
2bb00 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  igin_name16(sqli
2bb10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2bb20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bb30 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79   Declared Dataty
2bb40 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65  pe Of A Query Re
2bb50 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  sult.**.** ^(The
2bb60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2bb70 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2bb80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
2bb90 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74  f this statement
2bba0 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   is a [SELECT] s
2bbb0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65  tatement and the
2bbc0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2bbd0 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72  he.** returned r
2bbe0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61  esult set of tha
2bbf0 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20  t [SELECT] is a 
2bc00 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f  table column (no
2bc10 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  t an.** expressi
2bc20 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20  on or subquery) 
2bc30 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65  then the declare
2bc40 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61  d type of the ta
2bc50 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73  ble.** column is
2bc60 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49   returned.)^  ^I
2bc70 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2bc80 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2bc90 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
2bca0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2bcb0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
2bcc0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2bcd0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
2bce0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2bcf0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
2bd00 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
2bd10 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
2bd20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2bd30 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
2bd40 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
2bd50 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
2bd60 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
2bd70 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
2bd80 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
2bd90 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
2bda0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
2bdb0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
2bdc0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
2bdd0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
2bde0 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
2bdf0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
2be00 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
2be10 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
2be20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
2be30 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
2be40 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
2be50 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
2be60 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
2be70 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
2be80 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
2be90 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
2bea0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
2beb0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
2bec0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
2bed0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
2bee0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
2bef0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2bf00 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
2bf10 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
2bf20 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
2bf30 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
2bf40 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
2bf50 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
2bf60 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
2bf70 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
2bf80 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
2bf90 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
2bfa0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
2bfb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bfc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2bfd0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2bfe0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
2bff0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2c000 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2c010 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2c020 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c030 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2c040 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2c050 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2c060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c070 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2c080 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2c090 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c0a0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2c0b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c0c0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2c0d0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2c0e0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2c0f0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2c100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c110 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2c120 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2c130 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2c140 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2c150 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2c160 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2c170 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2c180 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2c190 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2c1a0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2c1b0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2c1c0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2c1d0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2c1e0 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2c1f0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2c200 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2c210 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2c220 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2c230 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2c240 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2c250 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2c260 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2c270 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2c280 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2c290 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2c2a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2c2b0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2c2c0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2c2d0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2c2e0 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2c2f0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2c300 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2c310 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2c320 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2c330 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2c340 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2c350 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2c360 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2c370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2c380 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2c390 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2c3a0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2c3b0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2c3c0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2c3d0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2c3e0 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2c3f0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2c400 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2c410 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2c420 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2c430 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2c440 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2c450 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2c460 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2c470 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2c480 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2c490 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2c4a0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2c4b0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2c4c0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2c4d0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2c4e0 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2c4f0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2c500 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2c510 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2c520 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2c530 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2c540 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2c550 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2c560 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2c570 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2c580 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2c590 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2c5a0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2c5b0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2c5c0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2c5d0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2c5e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2c5f0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2c600 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2c610 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2c620 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2c630 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2c640 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2c650 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2c660 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2c670 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2c680 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2c690 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2c6a0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2c6b0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2c6c0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2c6d0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2c6e0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2c6f0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2c700 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2c710 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2c720 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2c730 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2c740 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2c750 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2c760 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2c770 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2c780 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2c790 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2c7a0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2c7b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2c7c0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2c7d0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2c7e0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2c7f0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2c800 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2c810 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2c820 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2c830 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2c840 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2c850 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2c860 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2c870 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2c880 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2c890 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2c8a0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2c8b0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2c8c0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2c8d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2c8e0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2c8f0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2c900 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2c910 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2c920 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2c930 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c940 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2c950 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c960 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2c970 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2c980 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2c990 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2c9a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2c9b0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2c9c0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2c9d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c9e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2c9f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2ca00 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2ca10 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2ca20 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2ca30 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2ca40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2ca50 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2ca60 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2ca70 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2ca80 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2ca90 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2caa0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2cab0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2cac0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2cad0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2cae0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2caf0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2cb00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2cb10 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2cb20 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2cb30 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2cb40 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2cb50 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2cb60 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2cb70 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2cb80 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2cb90 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2cba0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2cbb0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2cbc0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2cbd0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2cbe0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2cbf0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2cc00 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2cc10 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2cc20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2cc30 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2cc40 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2cc50 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2cc60 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2cc70 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2cc80 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2cc90 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2cca0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2ccb0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2ccc0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2ccd0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2cce0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2ccf0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2cd00 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2cd10 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2cd20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2cd30 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2cd40 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2cd50 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2cd60 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2cd70 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2cd80 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2cd90 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2cda0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2cdb0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2cdc0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2cdd0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2cde0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2cdf0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2ce00 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2ce10 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2ce20 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2ce30 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2ce40 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2ce50 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2ce60 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2ce70 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2ce80 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2ce90 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2cea0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2ceb0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2cec0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2ced0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2cee0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2cef0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2cf00 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2cf10 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2cf20 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2cf30 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2cf40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2cf50 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2cf60 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2cf70 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2cf80 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2cf90 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2cfa0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2cfb0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2cfc0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2cfd0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2cfe0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2cff0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2d000 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2d010 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2d020 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2d030 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2d040 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2d050 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d060 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d070 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2d080 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2d090 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2d0a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2d0b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2d0c0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2d0d0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2d0e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2d0f0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2d100 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2d110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2d120 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2d130 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2d140 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2d150 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2d160 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
2d170 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d180 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
2d190 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
2d1a0 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
2d1b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d1c0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
2d1d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2d1e0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2d1f0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
2d200 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
2d210 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
2d220 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2d230 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
2d240 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
2d250 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
2d260 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
2d270 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
2d280 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
2d290 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
2d2a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
2d2b0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
2d2c0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
2d2d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2d2e0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
2d2f0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2d300 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
2d310 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
2d320 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
2d330 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
2d340 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2d350 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
2d360 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
2d370 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
2d380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2d390 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
2d3a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
2d3b0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2d3c0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
2d3d0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
2d3e0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
2d3f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2d400 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
2d410 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
2d420 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
2d430 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
2d440 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
2d450 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
2d460 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
2d470 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
2d480 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
2d490 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
2d4a0 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
2d4b0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
2d4c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2d4d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2d4e0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2d4f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2d500 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2d510 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d520 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2d530 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2d540 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2d550 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2d560 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2d570 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2d580 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2d590 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2d5a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2d5b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2d5c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2d5d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2d5e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2d5f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2d600 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2d610 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2d620 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2d630 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2d640 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2d650 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2d660 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2d670 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2d680 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2d690 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2d6a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2d6b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2d6c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2d6d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2d6e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2d6f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2d700 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2d710 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2d720 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2d730 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2d740 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2d750 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2d760 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2d770 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2d780 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2d790 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2d7a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2d7b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2d7c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2d7d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2d7e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2d7f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2d800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2d810 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2d820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2d830 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2d840 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2d850 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2d860 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2d870 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2d880 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2d890 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2d8a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2d8b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2d8c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2d8d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2d8e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2d8f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2d900 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2d910 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2d920 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2d930 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2d940 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2d950 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2d960 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2d970 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2d980 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2d990 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2d9a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2d9b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2d9c0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2d9d0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2d9e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2d9f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2da00 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2da10 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2da20 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2da30 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2da40 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2da50 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2da60 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2da70 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2da80 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2da90 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2daa0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2dab0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2dac0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2dad0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2dae0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2daf0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2db00 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2db10 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2db20 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2db30 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2db40 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2db50 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2db60 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2db70 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2db80 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2db90 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2dba0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2dbb0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2dbc0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2dbd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dbe0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2dbf0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2dc00 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2dc10 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2dc20 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2dc30 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2dc40 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2dc50 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2dc60 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2dc70 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2dc80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2dc90 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2dca0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2dcb0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2dcc0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2dcd0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2dce0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2dcf0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dd00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2dd10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2dd20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2dd30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2dd40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2dd50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2dd60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2dd70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2dd80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2dd90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2dda0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2ddb0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2ddc0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2ddd0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2dde0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2ddf0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2de00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2de10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2de20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2de30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2de40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2de50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2de60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2de70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2de80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2de90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2dea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2deb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2dec0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2ded0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2dee0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2def0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2df00 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2df10 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2df20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2df30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2df40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2df50 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2df60 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2df70 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2df80 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2df90 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2dfa0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2dfb0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2dfc0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2dfd0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2dfe0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2dff0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2e000 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2e010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e020 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2e030 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2e040 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2e050 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2e060 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2e070 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2e080 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2e090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e0a0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2e0b0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2e0c0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2e0d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e0e0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2e0f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e100 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2e110 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2e120 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2e130 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2e140 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2e150 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2e160 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2e170 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2e180 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2e190 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2e1a0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e1b0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e1c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e1d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2e1e0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2e1f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2e200 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2e210 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2e220 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2e230 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2e240 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2e250 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2e260 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2e270 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2e280 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2e290 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2e2a0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e2b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e2c0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2e2d0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2e2e0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2e2f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e300 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2e310 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2e320 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2e330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e340 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2e350 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2e360 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2e370 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2e380 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2e390 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2e3a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2e3b0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2e3c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2e3d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2e3e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2e3f0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2e400 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2e410 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2e420 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2e430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2e440 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2e450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e460 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2e470 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2e480 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2e490 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2e4a0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2e4b0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2e4c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2e4d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2e4e0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2e4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e500 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2e510 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2e520 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2e530 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2e540 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2e550 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2e560 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2e570 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2e580 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2e590 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2e5a0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2e5b0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2e5c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2e5d0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2e5e0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2e5f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2e600 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2e610 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2e620 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2e630 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2e640 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2e650 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2e660 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2e670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e680 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2e690 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2e6a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e6b0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2e6c0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2e6d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2e6e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e6f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2e700 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2e710 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e720 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2e730 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2e740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2e750 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2e760 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2e770 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2e780 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2e790 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2e7a0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2e7b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2e7c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2e7d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2e7e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2e7f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2e800 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2e810 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2e820 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2e830 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2e840 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2e850 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2e860 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2e870 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2e880 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2e890 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2e8a0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2e8b0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2e8c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2e8d0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2e8e0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2e8f0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2e900 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2e910 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2e920 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2e930 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2e940 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2e950 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2e960 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2e970 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2e980 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2e990 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2e9a0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2e9b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e9c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2e9d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e9e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2e9f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2ea00 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2ea10 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2ea20 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2ea30 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ea40 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
2ea50 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
2ea60 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2ea70 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2ea80 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2ea90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2eaa0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
2eab0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
2eac0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2ead0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
2eae0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2eaf0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2eb00 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2eb10 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2eb20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
2eb30 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2eb40 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2eb50 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
2eb60 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
2eb70 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2eb80 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2eb90 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2eba0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2ebb0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
2ebc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2ebd0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2ebe0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
2ebf0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2ec00 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ec10 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
2ec20 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
2ec30 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2ec40 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
2ec50 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
2ec60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ec70 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
2ec80 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2ec90 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
2eca0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ecb0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2ecc0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2ecd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2ece0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2ecf0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
2ed00 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
2ed10 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2ed20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
2ed30 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
2ed40 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
2ed50 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2ed60 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
2ed70 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
2ed80 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
2ed90 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
2eda0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
2edb0 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
2edc0 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
2edd0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
2ede0 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
2edf0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
2ee00 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
2ee10 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
2ee20 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
2ee30 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
2ee40 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
2ee50 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
2ee60 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
2ee70 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
2ee80 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
2ee90 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
2eea0 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
2eeb0 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
2eec0 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
2eed0 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
2eee0 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
2eef0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
2ef00 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
2ef10 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
2ef20 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
2ef30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ef40 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
2ef50 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
2ef60 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2ef70 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
2ef80 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
2ef90 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
2efa0 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
2efb0 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
2efc0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
2efd0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
2efe0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
2eff0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2f000 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2f010 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
2f020 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f030 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2f040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f050 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2f060 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
2f070 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
2f080 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
2f090 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
2f0a0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2f0b0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2f0c0 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
2f0d0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2f0e0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
2f0f0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2f100 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
2f110 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2f120 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2f130 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2f140 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
2f150 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
2f160 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
2f170 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
2f180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f190 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
2f1a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
2f1b0 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
2f1c0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
2f1d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
2f1e0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
2f1f0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
2f200 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
2f210 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
2f220 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
2f230 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
2f240 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
2f250 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
2f260 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
2f270 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
2f280 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
2f290 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
2f2a0 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
2f2b0 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
2f2c0 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
2f2d0 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
2f2e0 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
2f2f0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
2f300 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
2f310 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
2f320 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
2f330 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
2f340 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
2f350 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
2f360 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
2f370 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
2f380 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
2f390 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
2f3a0 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
2f3b0 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
2f3c0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
2f3d0 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
2f3e0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
2f3f0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
2f400 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f410 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
2f420 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f430 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
2f440 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
2f450 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
2f460 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f470 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
2f480 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
2f490 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f4a0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
2f4b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f4c0 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
2f4d0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
2f4e0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
2f4f0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
2f500 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f510 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
2f520 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
2f530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f540 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
2f550 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
2f560 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
2f570 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
2f580 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
2f590 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f5a0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2f5b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
2f5c0 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
2f5d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
2f5e0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
2f5f0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
2f600 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
2f610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f620 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
2f630 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2f640 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
2f650 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
2f660 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2f670 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2f680 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
2f690 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2f6a0 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
2f6b0 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
2f6c0 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
2f6d0 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
2f6e0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
2f6f0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
2f700 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
2f710 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f720 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2f730 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
2f740 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2f750 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
2f760 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
2f770 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
2f780 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
2f790 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
2f7a0 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
2f7b0 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
2f7c0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2f7d0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
2f7e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f7f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
2f800 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
2f810 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
2f820 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
2f830 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
2f840 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
2f850 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
2f860 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
2f870 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
2f880 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
2f890 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
2f8a0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
2f8b0 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
2f8c0 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
2f8d0 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
2f8e0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2f8f0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
2f900 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
2f910 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
2f920 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
2f930 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
2f940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
2f950 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
2f960 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2f970 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2f980 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f9a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2f9b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f9c0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2f9d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f9e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f9f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
2fa00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2fa10 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2fa20 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2fa30 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2fa40 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
2fa50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fa60 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
2fa70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fa80 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2fa90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2faa0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
2fab0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2fac0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
2fad0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2fae0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2faf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2fb00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
2fb10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
2fb20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2fb30 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
2fb40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2fb50 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
2fb60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2fb70 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2fb80 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2fb90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fba0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2fbb0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2fbc0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2fbd0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2fbe0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2fbf0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2fc00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fc10 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2fc20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2fc30 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2fc40 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2fc50 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2fc60 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2fc70 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2fc80 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2fc90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2fca0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2fcb0 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2fcc0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2fcd0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2fce0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2fcf0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2fd00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2fd10 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2fd20 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2fd30 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2fd40 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2fd50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2fd60 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2fd70 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2fd80 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2fd90 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2fda0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2fdb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fdc0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2fdd0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2fde0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2fdf0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2fe00 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2fe10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fe20 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2fe30 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2fe40 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2fe50 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2fe60 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2fe70 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2fe80 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2fe90 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2fea0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2feb0 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2fec0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2fed0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2fee0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2fef0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2ff00 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2ff10 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2ff20 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2ff30 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2ff40 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2ff50 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2ff60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2ff70 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2ff80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ff90 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2ffa0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2ffb0 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2ffc0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2ffd0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2ffe0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2fff0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
30000 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
30010 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
30020 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
30030 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
30040 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
30050 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
30060 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
30070 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
30080 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
30090 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
300a0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
300b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
300c0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
300d0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
300e0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
300f0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
30100 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
30110 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
30120 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
30130 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
30140 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
30150 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
30160 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
30170 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
30180 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30190 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
301a0 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
301b0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
301c0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
301d0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
301e0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
301f0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
30200 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
30210 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
30220 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
30230 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30240 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
30250 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
30260 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
30270 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30280 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
302a0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
302b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
302c0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
302d0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
302e0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
302f0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
30300 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
30310 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
30320 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
30330 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
30340 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
30350 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
30360 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
30370 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
30380 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
30390 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
303a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
303b0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
303c0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
303d0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
303e0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
303f0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
30400 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
30410 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
30420 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
30430 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
30440 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
30450 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30460 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
30470 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30480 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
30490 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
304a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
304b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
304c0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
304d0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
304e0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
304f0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
30500 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30510 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
30520 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
30530 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
30540 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
30550 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
30560 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
30570 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
30580 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
30590 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
305a0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
305b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
305c0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
305d0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
305e0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
305f0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
30600 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
30610 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
30620 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
30630 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
30640 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
30650 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
30660 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
30670 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
30680 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
30690 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
306a0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
306b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
306c0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
306d0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
306e0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
306f0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
30700 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
30710 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
30720 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
30730 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
30740 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
30750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30760 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
30770 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
30780 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
30790 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
307a0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
307b0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
307c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
307d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
307e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
307f0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
30800 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
30810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30820 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
30830 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
30840 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
30850 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
30860 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
30870 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
30880 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
30890 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
308a0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
308b0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
308c0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
308d0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
308e0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
308f0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
30900 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
30910 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
30920 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
30930 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
30940 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
30950 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
30960 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
30970 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
30980 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
30990 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
309a0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
309b0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
309c0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
309d0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
309e0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
309f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
30a00 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
30a10 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
30a20 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
30a30 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
30a40 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
30a50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
30a60 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
30a70 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
30a80 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
30a90 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
30aa0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
30ab0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
30ac0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
30ad0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
30ae0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
30af0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
30b00 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
30b10 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
30b20 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
30b30 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
30b40 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
30b50 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
30b60 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
30b70 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
30b80 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
30b90 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
30ba0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
30bb0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
30bc0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
30bd0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
30be0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
30bf0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
30c00 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
30c10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
30c20 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
30c30 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30c40 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
30c50 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
30c60 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
30c70 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
30c80 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
30c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30ca0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
30cb0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
30cc0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
30cd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30ce0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
30cf0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
30d00 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
30d10 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
30d20 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
30d30 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
30d40 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
30d50 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
30d60 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
30d70 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
30d80 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
30d90 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
30da0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
30db0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
30dc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
30dd0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
30de0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
30df0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
30e00 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
30e10 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
30e20 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
30e30 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
30e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
30e50 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
30e60 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
30e70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
30e80 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
30e90 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
30ea0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
30eb0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
30ec0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
30ed0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
30ee0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
30ef0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
30f00 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
30f10 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
30f20 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
30f30 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
30f40 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
30f50 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
30f60 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
30f70 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
30f80 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
30f90 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
30fa0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
30fb0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
30fc0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
30fd0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
30fe0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
30ff0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
31000 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
31010 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
31020 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
31030 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
31040 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
31050 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
31060 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
31070 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
31080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
31090 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
310a0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
310b0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
310c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
310d0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
310e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
310f0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
31100 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
31110 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
31120 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
31130 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
31140 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
31150 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
31160 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31170 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
31180 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
31190 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
311a0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
311b0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
311c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
311d0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
311e0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
311f0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
31200 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
31210 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
31220 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
31230 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
31240 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
31250 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
31260 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
31270 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
31280 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
31290 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
312a0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
312b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
312c0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
312d0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
312e0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
312f0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
31300 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
31310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
31320 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
31330 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
31340 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
31350 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
31360 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
31370 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
31380 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
31390 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
313a0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
313b0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
313c0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
313d0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
313e0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
313f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
31400 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
31410 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
31420 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
31430 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
31440 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
31450 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
31460 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
31470 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
31480 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
31490 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
314a0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
314b0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
314c0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
314d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
314e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
314f0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
31500 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
31510 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
31520 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31530 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
31540 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
31550 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
31560 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
31570 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
31580 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
31590 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
315a0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
315b0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
315c0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
315d0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
315e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
315f0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
31600 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
31610 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
31620 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
31630 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
31640 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
31650 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
31660 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
31670 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
31680 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
31690 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
316a0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
316b0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
316c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
316d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
316e0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
316f0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
31700 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
31710 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31720 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
31730 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
31740 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
31750 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
31760 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
31770 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
31780 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
31790 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
317a0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
317b0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
317c0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
317d0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
317e0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
317f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31800 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31810 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
31820 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
31830 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
31840 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
31850 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
31860 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
31870 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31880 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
31890 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
318a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
318b0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
318c0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
318d0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
318e0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
318f0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
31900 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
31910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31920 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
31930 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
31940 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
31950 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
31960 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
31970 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
31980 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31990 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
319a0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
319b0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
319c0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
319d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
319e0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
319f0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31a00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31a10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31a20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
31a30 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
31a40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31a50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31a60 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
31a70 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
31a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
31a90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
31aa0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
31ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
31ac0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
31ad0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
31ae0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
31af0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
31b00 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
31b10 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
31b20 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
31b30 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
31b40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31b50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31b60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
31b70 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
31b80 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
31b90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31ba0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
31bb0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
31bc0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
31bd0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
31be0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
31bf0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
31c00 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
31c10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
31c20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
31c30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
31c40 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
31c50 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31c60 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31c70 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
31c80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
31c90 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
31ca0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
31cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
31cc0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
31cd0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
31ce0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
31cf0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
31d00 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
31d10 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
31d20 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
31d30 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
31d40 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
31d50 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
31d60 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
31d70 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
31d80 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
31d90 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
31da0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
31db0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
31dc0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
31dd0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
31de0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
31df0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
31e00 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23   Deprecated */.#
31e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
31e20 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
31e30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
31e40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
31e50 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
31e60 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
31e70 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Flags.**.** Thes
31e80 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20  e constants may 
31e90 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72  be ORed together
31ea0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
31eb0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65  QLITE_UTF8 | pre
31ec0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
31ed0 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75  ding] as the fou
31ee0 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
31ef0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
31f00 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
31f10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
31f20 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  function16()], o
31f30 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
31f40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
31f50 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
31f60 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31f70 53 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f  STIC    0x800../
31f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31f90 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
31fa0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
31fb0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
31fc0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
31fd0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
31fe0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
31ff0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
32000 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
32010 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
32020 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
32030 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
32040 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
32050 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
32060 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
32070 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
32080 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
32090 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
320a0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
320b0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
320c0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
320d0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
320e0 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
320f0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
32100 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
32110 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
32120 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
32130 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32140 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
32150 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32160 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
32170 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
32180 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
32190 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
321a0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
321b0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
321c0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
321d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
321e0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
321f0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  ED int sqlite3_g
32200 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f  lobal_recover(vo
32210 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  id);.SQLITE_DEPR
32220 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
32230 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
32240 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
32250 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
32260 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61  sqlite3_memory_a
32270 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69  larm(void(*)(voi
32280 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
32290 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20  ,int),.         
322a0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69               voi
322b0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
322c0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
322d0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
322e0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
322f0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
32300 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
32310 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
32320 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
32330 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
32340 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
32350 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
32360 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
32370 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
32380 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
32390 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
323a0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
323b0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
323c0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
323d0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
323e0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
323f0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
32400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32410 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
32420 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32430 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
32440 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
32450 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
32460 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32470 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
32480 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
32490 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
324a0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
324b0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
324c0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
324d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
324e0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
324f0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
32500 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32510 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
32520 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
32530 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
32540 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
32550 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
32560 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
32570 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
32580 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
32590 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
325a0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
325b0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
325c0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
325d0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
325e0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
325f0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
32600 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
32610 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
32620 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
32630 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
32640 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
32650 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
32660 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
32670 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
32680 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
32690 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
326a0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
326b0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
326c0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
326d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
326e0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
326f0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
32700 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
32710 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
32720 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
32730 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32740 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
32750 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
32760 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
32770 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
32780 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
32790 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
327a0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
327b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
327c0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
327d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
327e0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
327f0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
32800 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
32810 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
32820 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
32830 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
32840 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
32850 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
32860 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
32870 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
32880 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
32890 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
328a0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
328b0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
328c0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
328d0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
328e0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
328f0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
32900 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
32910 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
32920 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
32930 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
32940 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
32950 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
32960 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
32970 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
32980 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
32990 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
329a0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
329b0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
329c0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
329d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
329e0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
329f0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
32a00 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
32a10 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
32a20 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
32a30 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
32a40 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
32a50 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
32a60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32a70 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
32a80 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32a90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32aa0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
32ab0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
32ac0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
32ad0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
32ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32af0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
32b00 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
32b10 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32b20 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32b30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
32b40 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
32b50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
32b60 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
32b70 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
32b80 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
32b90 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
32ba0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
32bb0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
32bc0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
32bd0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32be0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
32bf0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32c10 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
32c20 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
32c30 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
32c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32c50 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
32c60 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
32c70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
32c80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
32c90 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
32ca0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
32cb0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
32cc0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
32cd0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
32ce0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
32cf0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
32d00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32d10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32d20 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32d30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32d40 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
32d50 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32d60 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
32d70 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32d80 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32d90 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
32da0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
32db0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
32dc0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32dd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
32de0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
32df0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32e00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32e10 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
32e20 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
32e30 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
32e40 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67  mentations of ag
32e50 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
32e60 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
32e70 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
32e80 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
32e90 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
32ea0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
32eb0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
32ec0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
32ed0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
32ee0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
32ef0 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
32f00 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
32f10 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
32f20 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
32f30 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
32f40 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
32f50 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
32f60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
32f70 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
32f80 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
32f90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
32fa0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
32fb0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32fc0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
32fd0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32fe0 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
32ff0 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
33000 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
33010 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33020 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
33030 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
33040 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
33050 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
33060 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
33070 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
33080 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
33090 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
330a0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
330b0 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
330c0 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
330d0 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
330e0 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
330f0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
33100 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
33110 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
33120 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
33130 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
33140 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
33150 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
33160 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
33170 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
33180 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
33190 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
331a0 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
331b0 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
331c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
331d0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
331e0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
331f0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
33200 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69  nter .** when fi
33210 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20  rst called if N 
33220 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  is less than or 
33230 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
33240 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20   if a memory.** 
33250 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
33260 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
33270 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
33280 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
33290 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
332a0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
332b0 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
332c0 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
332d0 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
332e0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
332f0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
33300 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
33310 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
33320 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
33330 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
33340 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
33350 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
33360 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
33370 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
33380 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
33390 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68  on.)^  Within th
333a0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
333b0 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61  k, it is customa
333c0 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30  ry to set.** N=0
333d0 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c   in calls to sql
333e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
333f0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74  ontext(C,N) so t
33400 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74  hat no .** point
33410 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  less memory allo
33420 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a  cations occur..*
33430 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
33440 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
33450 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
33460 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
33470 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33480 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
33490 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
334a0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
334b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
334c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
334d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
334e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
334f0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
33500 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
33510 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
33520 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
33530 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
33540 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
33550 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
33560 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
33570 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33580 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
33590 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
335a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
335b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
335c0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
335d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
335e0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
335f0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33600 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
33610 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
33620 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
33630 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
33640 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
33650 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33660 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
33670 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33680 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33690 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
336a0 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
336b0 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
336c0 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
336d0 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
336e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
336f0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
33700 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33710 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
33720 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
33730 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
33740 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33750 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
33760 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
33770 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
33780 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
33790 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
337a0 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
337b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
337c0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
337d0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
337e0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
337f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
33800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33810 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
33820 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
33830 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33840 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
33850 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
33860 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
33870 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
33880 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
33890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
338a0 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
338b0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
338c0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
338d0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
338e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
338f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
33900 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
33910 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
33920 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
33930 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
33940 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
33950 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
33960 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
33970 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33980 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33990 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
339a0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
339b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
339c0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
339d0 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
339e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
339f0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
33a00 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
33a10 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
33a20 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
33a30 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
33a40 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
33a50 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
33a60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
33a70 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
33a80 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
33a90 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
33aa0 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
33ab0 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
33ac0 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
33ad0 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
33ae0 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
33af0 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
33b00 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
33b10 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
33b20 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
33b30 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
33b40 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
33b50 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
33b60 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
33b70 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
33b80 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
33b90 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
33ba0 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
33bb0 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
33bc0 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
33bd0 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
33be0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
33bf0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
33c00 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
33c10 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
33c20 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
33c30 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
33c40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
33c50 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
33c60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
33c70 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
33c80 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
33c90 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
33ca0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
33cb0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
33cc0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
33cd0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
33ce0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33cf0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
33d00 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
33d10 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
33d20 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
33d30 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
33d40 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
33d50 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
33d60 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
33d70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
33d80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33d90 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33da0 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
33db0 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
33dc0 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
33dd0 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
33de0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33df0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33e00 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
33e10 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
33e20 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
33e30 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
33e40 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
33e50 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
33e60 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
33e70 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
33e80 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
33e90 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
33ea0 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
33eb0 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
33ec0 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
33ed0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
33ee0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33ef0 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
33f00 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
33f10 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
33f20 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
33f30 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
33f40 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
33f50 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
33f60 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
33f70 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
33f80 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
33f90 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
33fa0 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
33fb0 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
33fc0 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
33fd0 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
33fe0 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
33ff0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
34000 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
34010 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
34020 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34030 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
34040 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
34050 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
34060 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
34070 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
34080 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
34090 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
340a0 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
340b0 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
340c0 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
340d0 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
340e0 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
340f0 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
34100 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
34110 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
34120 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
34130 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
34140 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
34150 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
34160 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
34170 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
34180 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
34190 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
341a0 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
341b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
341c0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
341d0 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
341e0 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
341f0 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
34200 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
34210 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
34220 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
34230 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
34240 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
34250 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
34260 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
34270 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
34280 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
34290 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
342a0 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
342b0 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
342c0 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
342d0 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
342e0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
342f0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
34300 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
34310 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
34320 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
34330 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
34340 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
34350 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
34360 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
34370 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
34380 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
34390 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
343a0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
343b0 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
343c0 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
343d0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
343e0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
343f0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
34400 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34410 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
34420 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
34430 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
34440 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
34450 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
34460 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
34470 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
34480 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
34490 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
344a0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
344b0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
344c0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
344d0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
344e0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
344f0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
34500 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
34510 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
34520 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
34530 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
34540 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
34550 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
34560 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
34570 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
34580 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
34590 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
345a0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
345b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
345c0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
345d0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
345e0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
345f0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
34600 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
34610 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
34620 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
34630 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
34640 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
34650 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
34660 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
34670 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
34680 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
34690 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
346a0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
346b0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
346c0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
346d0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
346e0 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
346f0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
34700 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
34710 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
34720 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
34730 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
34740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
34750 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
34760 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
34770 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
34780 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
34790 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
347a0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
347b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
347c0 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
347d0 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
347e0 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
347f0 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
34800 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34810 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
34820 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
34830 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34840 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34850 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34860 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
34870 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
34880 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
34890 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
348a0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
348b0 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
348c0 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
348d0 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
348e0 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
348f0 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
34900 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
34910 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
34920 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
34930 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
34940 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
34950 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
34960 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
34970 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
34980 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
34990 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
349a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
349b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
349c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
349d0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
349e0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
349f0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
34a00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
34a10 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
34a20 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
34a30 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
34a40 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34a50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34a60 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
34a70 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
34a80 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
34a90 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
34aa0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
34ab0 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
34ac0 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
34ad0 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
34ae0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
34af0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
34b00 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
34b10 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
34b20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34b30 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
34b40 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
34b50 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
34b60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
34b70 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34b80 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
34b90 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
34ba0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
34bb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
34bc0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34bd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34be0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34bf0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
34c00 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
34c10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
34c20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
34c30 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
34c40 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
34c50 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
34c60 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
34c70 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
34c80 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
34c90 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
34ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34cb0 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
34cc0 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
34cd0 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
34ce0 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
34cf0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
34d00 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
34d10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34d20 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
34d30 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
34d40 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
34d50 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
34d60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34d70 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
34d80 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
34d90 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
34da0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34db0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34dc0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
34dd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34de0 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
34df0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
34e00 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
34e10 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
34e20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
34e30 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
34e40 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
34e50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
34e60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
34e70 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
34e80 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
34e90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
34ea0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
34eb0 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34ec0 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
34ed0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
34ee0 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
34ef0 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
34f00 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
34f10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34f20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34f30 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34f40 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
34f50 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
34f60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
34f70 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
34f80 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
34f90 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
34fa0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
34fb0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
34fc0 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
34fd0 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
34fe0 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
34ff0 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
35000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35010 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
35020 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
35030 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
35040 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
35050 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
35060 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
35070 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
35080 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
35090 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
350a0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
350b0 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
350c0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
350d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
350e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
350f0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
35100 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
35110 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
35120 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
35130 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35140 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
35150 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
35160 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
35170 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
35180 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
35190 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
351a0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
351b0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
351c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
351d0 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
351e0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
351f0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
35200 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
35210 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
35220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
35230 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
35240 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35250 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
35260 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
35270 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
35280 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35290 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
352a0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
352b0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
352c0 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
352d0 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
352e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
352f0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
35300 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35310 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
35320 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
35330 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35340 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
35350 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
35360 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
35370 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
35380 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
35390 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
353a0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
353b0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
353c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
353d0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
353e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
353f0 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
35400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35410 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
35420 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
35430 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
35440 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
35450 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
35460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
35470 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
35480 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
35490 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
354a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
354b0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
354c0 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
354d0 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
354e0 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
354f0 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
35500 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
35510 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
35520 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
35530 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
35540 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
35550 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
35560 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
35570 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
35580 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
35590 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
355a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
355b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
355c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
355d0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
355e0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
355f0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35600 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
35610 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
35620 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
35630 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
35640 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
35650 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
35660 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
35670 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
35680 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
35690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
356a0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
356b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
356c0 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
356d0 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
356e0 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
356f0 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
35700 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
35710 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
35720 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
35730 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
35740 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
35750 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
35760 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
35770 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
35780 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
35790 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
357a0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
357b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
357c0 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
357d0 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
357e0 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
357f0 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
35800 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
35810 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
35820 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
35830 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
35840 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
35850 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
35860 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
35870 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
35880 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
35890 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
358a0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
358b0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
358c0 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
358d0 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
358e0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
358f0 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
35900 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
35910 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35920 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35930 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
35940 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
35950 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
35960 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
35970 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
35980 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
35990 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
359a0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
359b0 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
359c0 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
359d0 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
359e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
359f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
35a00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35a10 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
35a20 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
35a30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35a40 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35a50 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
35a60 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
35a70 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
35a80 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
35a90 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
35aa0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
35ab0 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
35ac0 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
35ad0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
35ae0 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
35af0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
35b00 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
35b10 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
35b20 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
35b30 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
35b40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
35b50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35b60 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35b70 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
35b80 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
35b90 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
35ba0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
35bb0 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
35bc0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
35bd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
35be0 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
35bf0 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
35c00 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
35c10 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
35c20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
35c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
35c40 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
35c50 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35c60 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
35c70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35c80 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
35c90 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
35ca0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35cb0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
35cc0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
35cd0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
35ce0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
35cf0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
35d00 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35d10 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35d20 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
35d30 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
35d40 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
35d50 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
35d60 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
35d70 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
35d80 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
35d90 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35da0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
35db0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
35dc0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35dd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35de0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
35df0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
35e00 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35e10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35e20 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
35e30 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
35e40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
35e50 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
35e60 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
35e70 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
35e80 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
35e90 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
35ea0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
35eb0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
35ec0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
35ed0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
35ee0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35ef0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
35f00 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
35f10 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
35f20 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
35f30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
35f40 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
35f50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35f60 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
35f70 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35f80 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
35f90 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
35fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
35fb0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35fc0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f  xt*, double);.vo
35fd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35fe0 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f  t_error(sqlite3_
35ff0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
36000 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  char*, int);.voi
36010 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36020 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33  _error16(sqlite3
36030 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
36040 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f   void*, int);.vo
36050 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36060 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
36070 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
36080 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36090 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
360a0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
360b0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
360c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
360d0 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ode(sqlite3_cont
360e0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
360f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36100 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  int(sqlite3_cont
36110 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64  ext*, int);.void
36120 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36130 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
36140 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
36150 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c  int64);.void sql
36160 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c  ite3_result_null
36170 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36180 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
36190 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c  _result_text(sql
361a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
361b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c  onst char*, int,
361c0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
361d0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
361e0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
361f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
36200 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
36210 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
36220 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36230 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73  esult_text16le(s
36240 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36250 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36260 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
36270 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36280 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
36290 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
362a0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
362b0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
362c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
362d0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
362e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
362f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
36300 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
36310 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
36320 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36330 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
36340 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
36350 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
36360 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
36370 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
36380 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
36390 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
363a0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
363b0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
363c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
363d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
363e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
363f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
36400 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
36410 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
36420 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
36430 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36440 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
36450 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36460 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
36470 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
36480 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
36490 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
364a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
364b0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
364c0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
364d0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
364e0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
364f0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
36500 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
36510 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
36520 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
36530 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
36540 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
36550 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
36560 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
36570 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
36580 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
36590 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
365a0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
365b0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
365c0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
365d0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
365e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
365f0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
36600 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
36610 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
36620 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
36630 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
36640 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
36650 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36660 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
36670 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
36680 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
36690 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
366a0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
366b0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
366c0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
366d0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
366e0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
366f0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
36700 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36710 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
36720 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
36730 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
36740 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
36750 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
36760 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
36770 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
36780 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
36790 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
367a0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
367b0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
367c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
367d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
367e0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
367f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
36800 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
36810 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
36820 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
36830 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
36840 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
36850 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
36860 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
36870 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
36880 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
36890 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
368a0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
368b0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
368c0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
368d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
368e0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
368f0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
36900 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
36910 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
36920 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
36930 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
36940 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
36950 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
36960 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
36970 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
36980 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
36990 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
369a0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
369b0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
369c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
369d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
369e0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
369f0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
36a00 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
36a10 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
36a20 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
36a30 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
36a40 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
36a50 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
36a60 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
36a70 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
36a80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36a90 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
36aa0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
36ab0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
36ac0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
36ad0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
36ae0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
36af0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
36b00 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
36b10 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
36b20 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
36b30 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
36b40 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
36b50 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
36b60 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
36b70 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
36b80 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
36b90 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
36ba0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
36bb0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
36bc0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
36bd0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
36be0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
36bf0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
36c00 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
36c10 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
36c20 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
36c30 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
36c40 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
36c50 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
36c60 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
36c70 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
36c80 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
36c90 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
36ca0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
36cb0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
36cc0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
36cd0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
36ce0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
36cf0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
36d00 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
36d10 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
36d20 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
36d30 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
36d40 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
36d50 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
36d60 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
36d70 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
36d80 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
36d90 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
36da0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
36db0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
36dc0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
36dd0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
36de0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36df0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36e00 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36e10 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
36e20 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
36e30 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
36e40 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
36e50 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
36e60 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
36e70 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
36e80 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36e90 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
36ea0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
36eb0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
36ec0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
36ed0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
36ee0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
36ef0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
36f00 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
36f10 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
36f20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36f30 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
36f40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
36f50 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
36f60 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
36f70 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
36f80 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
36f90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
36fa0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
36fb0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
36fc0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
36fd0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
36fe0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36ff0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
37000 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
37010 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
37020 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
37030 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
37040 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
37050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37060 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
37070 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
37080 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
37090 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
370a0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
370b0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
370c0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
370d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
370e0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
370f0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
37100 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
37110 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
37120 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
37130 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
37140 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
37150 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
37160 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
37170 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
37180 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
37190 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
371a0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
371b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
371c0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  tion(.  sqlite3*
371d0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
371e0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
371f0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
37200 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
37210 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
37220 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
37230 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
37240 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
37250 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37260 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
37270 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37280 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
37290 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
372a0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
372b0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
372c0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
372d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
372e0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
372f0 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73  (void*).);.int s
37300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37310 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  llation16(.  sql
37320 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37330 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69  void *zName,.  i
37340 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
37350 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
37360 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
37370 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37380 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
37390 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
373a0 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f  PI3REF: Collatio
373b0 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63  n Needed Callbac
373c0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f  ks.**.** ^To avo
373d0 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67  id having to reg
373e0 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74  ister all collat
373f0 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65  ion sequences be
37400 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a  fore a database.
37410 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20  ** can be used, 
37420 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63  a single callbac
37430 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  k function may b
37440 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
37450 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  h the.** [databa
37460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
37470 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
37480 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e  never an undefin
37490 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20  ed collation.** 
374a0 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75  sequence is requ
374b0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ired..**.** ^If 
374c0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
374d0 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
374e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
374f0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
37500 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  API,.** then it 
37510 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61  is passed the na
37520 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64  mes of undefined
37530 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37540 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a  nces as strings.
37550 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54  ** encoded in UT
37560 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33  F-8. ^If sqlite3
37570 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37580 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a  d16() is used,.*
37590 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20  * the names are 
375a0 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36  passed as UTF-16
375b0 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69   in machine nati
375c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
375d0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74  * ^A call to eit
375e0 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70  her function rep
375f0 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69  laces the existi
37600 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65  ng collation-nee
37610 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ded callback..**
37620 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63  .** ^(When the c
37630 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37640 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72  ed, the first ar
37650 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73  gument passed is
37660 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68   a copy.** of th
37670 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
37680 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  t to sqlite3_col
37690 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20  lation_needed() 
376a0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
376b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
376c0 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ().  The second 
376d0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
376e0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
376f0 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69  ection.  The thi
37700 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  rd argument is o
37710 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54  ne of [SQLITE_UT
37720 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
37730 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  16BE],.** or [SQ
37740 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69  LITE_UTF16LE], i
37750 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f  ndicating the mo
37760 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72  st desirable for
37770 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  m of the collati
37780 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66  on.** sequence f
37790 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64  unction required
377a0 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
377b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
377c0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65  ame of the.** re
377d0 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  quired collation
377e0 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a   sequence.)^.**.
377f0 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
37800 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
37810 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73  register the des
37820 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75  ired collation u
37830 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
37840 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37850 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
37860 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
37870 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
37880 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37890 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ation_v2()]..*/.
378a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
378b0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20  ation_needed(.  
378c0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
378d0 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76  d*, .  void(*)(v
378e0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
378f0 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37900 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73   char*).);.int s
37910 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
37920 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c  _needed16(.  sql
37930 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
37940 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
37950 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
37960 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69  extRep,const voi
37970 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53  d*).);..#ifdef S
37980 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a  QLITE_HAS_CODEC.
37990 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
379a0 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63  e key for an enc
379b0 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e  rypted database.
379c0 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73    This routine s
379d0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c  hould be.** call
379e0 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73  ed right after s
379f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a  qlite3_open()..*
37a00 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f  *.** The code to
37a10 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20   implement this 
37a20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c  API is not avail
37a30 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c  able in the publ
37a40 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66  ic release.** of
37a50 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20   SQLite..*/.int 
37a60 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
37a70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
37a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
37a90 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
37aa0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
37ab0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37ac0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37ad0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74  he key */.);.int
37ae0 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28   sqlite3_key_v2(
37af0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37b00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37b10 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37b20 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37b30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37b40 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20  Name,           
37b50 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64  /* Name of the d
37b60 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
37b70 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
37b80 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
37b90 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
37ba0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
37bb0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
37bc0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
37bd0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
37be0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
37bf0 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
37c00 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
37c10 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
37c20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
37c30 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
37c40 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
37c50 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
37c60 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
37c70 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
37c80 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
37c90 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
37ca0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
37cb0 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69  e3_rekey(.  sqli
37cc0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37cd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
37ce0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
37cf0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
37d00 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
37d10 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
37d20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e  new key */.);.in
37d30 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f  t sqlite3_rekey_
37d40 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
37d50 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
37d60 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
37d70 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
37d80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
37d90 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
37da0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
37db0 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  e database */.  
37dc0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
37dd0 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
37de0 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
37df0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
37e00 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
37e10 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
37e20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
37e30 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
37e40 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
37e50 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
37e60 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
37e70 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
37e80 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
37e90 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
37ea0 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
37eb0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
37ec0 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
37ed0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
37ee0 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
37ef0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
37f00 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
37f10 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
37f20 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
37f30 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
37f40 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
37f50 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
37f60 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
37f70 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
37f80 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
37f90 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
37fa0 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
37fb0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
37fc0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
37fd0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
37fe0 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
37ff0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
38000 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
38010 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
38020 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
38030 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
38040 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
38050 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
38060 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
38070 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
38080 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
38090 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
380a0 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
380b0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
380c0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
380d0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
380e0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
380f0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
38100 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
38110 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
38120 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
38130 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
38140 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
38150 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
38160 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
38170 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
38180 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
38190 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
381a0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
381b0 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
381c0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
381d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
381e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
381f0 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
38200 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
38210 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
38220 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
38230 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
38240 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
38250 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
38260 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
38270 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
38280 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
38290 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
382a0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
382b0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
382c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
382d0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
382e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
382f0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
38300 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
38310 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
38320 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
38330 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
38340 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
38350 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
38360 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
38370 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
38380 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
38390 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
383a0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
383b0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
383c0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
383d0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
383e0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
383f0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
38400 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
38410 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
38420 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
38430 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
38440 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
38450 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
38460 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
38470 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
38480 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
38490 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
384a0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
384b0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
384c0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
384d0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
384e0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
384f0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
38500 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
38510 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
38520 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
38530 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
38540 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
38550 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
38560 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
38570 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
38580 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
38590 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
385a0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
385b0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
385c0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
385d0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
385e0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
385f0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
38600 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
38610 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
38620 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
38630 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
38640 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
38650 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
38660 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
38670 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
38680 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
38690 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
386a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
386b0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
386c0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
386d0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
386e0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
386f0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
38700 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
38710 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
38720 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
38730 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
38740 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
38750 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
38760 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
38770 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
38780 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
38790 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
387a0 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
387b0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
387c0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
387d0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
387e0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
387f0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
38800 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
38810 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
38820 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
38830 72 20