System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1241d684a5cab24ddee37cec2e32f1d317295dc9:


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 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 31 32 22 0a 23 64 65 66 69 6e 65 20 53  .7.12".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 32 0a 23 64 65  MBER 3007012.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 30 35 2d 31 32 20 31 38 3a 32 39 3a 35 33 20  -05-12 18:29:53 
1080: 65 35 33 36 61 63 30 34 31 38 31 35 62 31 31 38  e536ac041815b118
1090: 63 34 36 31 63 65 65 65 37 39 38 66 39 62 37 32  c461ceee798f9b72
10a0: 38 33 32 36 39 66 35 38 22 0a 0a 2f 2a 0a 2a 2a  83269f58"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20  _close()].** is 
2490: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20  its destructor. 
24a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
24b0: 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  other interfaces
24c0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
24e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
24f0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2500: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2510: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2520: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2530: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2540: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2550: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2560: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2570: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
2580: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2590: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25a0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25b0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25c0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25d0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
25e0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
25f0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2600: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2610: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2620: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2630: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2640: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2650: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2660: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2670: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2680: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
2690: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26a0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26b0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26c0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26d0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
26e0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
26f0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2700: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2710: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2720: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2730: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2740: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2750: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2760: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2770: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
2780: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
2790: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27c0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27d0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
27e0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
27f0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2800: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2810: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2820: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2830: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2840: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2850: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2860: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2870: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
2880: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
2890: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28a0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28b0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28c0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
28e0: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
28f0: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2900: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2910: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2920: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2930: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2940: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2950: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2960: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2970: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2980: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
2990: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29a0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29b0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29c0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29d0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
29e0: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
29f0: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a00: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a10: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a20: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a30: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a40: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a50: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a60: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a70: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2a80: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2a90: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2aa0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ab0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ac0: 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64  routine is the d
2ad0: 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68  estructor for th
2ae0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2af0: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
2b00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2b10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b20: 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  K if the [sqlite
2b30: 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  3] object is.** 
2b40: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2b50: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2b60: 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72  ssociated resour
2b70: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2b80: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ted..**.** Appli
2b90: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71  cations must [sq
2ba0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
2bb0: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
2bc0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd0: 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  nts].** and [sql
2be0: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
2bf0: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
2c00: 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f  OB handles] asso
2c10: 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74  ciated with.** t
2c20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2c30: 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74  ect prior to att
2c40: 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65  empting to close
2c50: 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49   the object.  ^I
2c60: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f  f.** sqlite3_clo
2c70: 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  se() is called o
2c80: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
2c90: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
2ca0: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
2cb0: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
2cc0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72  d statements] or
2cd0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2ce0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2cf0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
2d00: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69  .**.** ^If [sqli
2d10: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20  te3_close()] is 
2d20: 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20  invoked while a 
2d30: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
2d40: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
2d50: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
2d60: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2d70: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
2d80: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
2d90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
2da0: 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  ] must be either
2db0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2dc0: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65  er or an [sqlite
2dd0: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65  3] object pointe
2de0: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  r obtained.** fr
2df0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  om [sqlite3_open
2e00: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2e10: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  en16()], or.** [
2e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2e30: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76  )], and not prev
2e40: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a  iously closed..*
2e50: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
2e60: 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20  e3_close() with 
2e70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
2e80: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a  rgument is a .**
2e90: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2ea0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2eb0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
2ec0: 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a  (sqlite3 *);../*
2ed0: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72  .** The type for
2ee0: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
2ef0: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73  tion..** This is
2f00: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72   legacy and depr
2f10: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69  ecated.  It is i
2f20: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74  ncluded for hist
2f30: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74  orical.** compat
2f40: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e  ibility and is n
2f50: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a  ot documented..*
2f60: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a  /.typedef int (*
2f70: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b  sqlite3_callback
2f80: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
2f90: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a  **, char**);../*
2fa0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e  .** CAPI3REF: On
2fb0: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65  e-Step Query Exe
2fc0: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65  cution Interface
2fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fe0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
2ff0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
3000: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
3010: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
3020: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
3030: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3040: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3050: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3060: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3070: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3080: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3090: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
30a0: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
30b0: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
30c0: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
30d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
30e0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
30f0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
3100: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
3110: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
3120: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3130: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3140: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3150: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3160: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3180: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3190: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
31a0: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
31b0: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
31c0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
31d0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
31e0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
31f0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
3200: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
3210: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
3220: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
3230: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3240: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3250: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3260: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3270: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3280: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3290: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
32a0: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
32b0: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
32c0: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
32d0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
32e0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
32f0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
3300: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
3310: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
3320: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
3330: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3340: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3350: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3360: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3370: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3380: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3390: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
33a0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
33b0: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
33c0: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
33d0: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
33e0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
33f0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3400: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
3410: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
3420: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
3430: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3440: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3450: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3460: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3470: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3480: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3490: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
34a0: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
34b0: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
34c0: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
34d0: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
34e0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
34f0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3500: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3510: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3520: 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  of.** of sqlite3
3530: 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68  _exec() after th
3540: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
3550: 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e  string is no lon
3560: 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e  ger needed..** ^
3570: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
3580: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3590: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
35a0: 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73  LL and no errors
35b0: 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20  .** occur, then 
35c0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73  sqlite3_exec() s
35d0: 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ets the pointer 
35e0: 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d  in its 5th param
35f0: 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20  eter to.** NULL 
3600: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
3610: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73  ..**.** ^If an s
3620: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3630: 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
3640: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c  on-zero, the sql
3650: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72  ite3_exec().** r
3660: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53  outine returns S
3670: 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68  QLITE_ABORT with
3680: 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  out invoking the
3690: 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20   callback again 
36a0: 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72  and.** without r
36b0: 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65  unning any subse
36c0: 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d  quent SQL statem
36d0: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
36e0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   2nd argument to
36f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3700: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  c() callback fun
3710: 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20  ction is the.** 
3720: 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
3730: 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  s in the result.
3740: 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d    ^The 3rd argum
3750: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3760: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c  e3_exec().** cal
3770: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3780: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3790: 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65   strings obtaine
37a0: 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20  d as if from.** 
37b0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
37c0: 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72  text()], one for
37d0: 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e   each column.  ^
37e0: 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66  If an element of
37f0: 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77   a.** result row
3800: 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68   is NULL then th
3810: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
3820: 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66  string pointer f
3830: 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  or the.** sqlite
3840: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3850: 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  k is a NULL poin
3860: 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61  ter.  ^The 4th a
3870: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
3880: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3890: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
38a0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
38b0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65  s to strings whe
38c0: 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79  re each.** entry
38d0: 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20   represents the 
38e0: 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f  name of correspo
38f0: 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c  nding result col
3900: 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a  umn as obtained.
3910: 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
3920: 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e  _column_name()].
3930: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32  .**.** ^If the 2
3940: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
3950: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3970: 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  , a pointer.** t
3980: 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
3990: 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20  g, or a pointer 
39a0: 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e  that contains on
39b0: 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e  ly whitespace an
39c0: 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d  d/or .** SQL com
39d0: 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53  ments, then no S
39e0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
39f0: 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20  e evaluated and 
3a00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
3a10: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a  is not changed..
3a20: 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f  **.** Restrictio
3a30: 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ns:.**.** <ul>.*
3a40: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3a50: 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75  cation must insu
3a60: 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20  re that the 1st 
3a70: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a80: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20  ite3_exec().**  
3a90: 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61      is a valid a
3aa0: 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  nd open [databas
3ab0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
3ac0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
3ad0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
3ae0: 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20  close [database 
3af0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3b00: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3b10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3b20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b30: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3b50: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3b60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3b70: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3b80: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3b90: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3ba0: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3bb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3bc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3bd0: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3be0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3bf0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
3c00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
3c10: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
3c20: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
3c50: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
3c60: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
3c90: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
3ca0: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
3cb0: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3cc0: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
3cd0: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
3ce0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d10: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
3d20: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
3d30: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
3d40: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d60: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
3d70: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
3d80: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3d90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
3da0: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
3db0: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
3dc0: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
3dd0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
3de0: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
3df0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
3e00: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
3e10: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
3e20: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
3e30: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
3e40: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
3e50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
3e60: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
3f00: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
3f10: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
3f20: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
3f30: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
3f40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
3f50: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
3f60: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
3f70: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
3f80: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
3f90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3fa0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
3fb0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
3fc0: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
3fd0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
3fe0: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
3ff0: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4000: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4010: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4020: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4030: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
4040: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
4050: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
4060: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
4070: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
4080: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
4090: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
40a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40b0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
40c0: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
40d0: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
40e0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
40f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4100: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4110: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4120: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
4140: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
4150: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
4160: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4170: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
4180: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
4190: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
41a0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
41b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
41c0: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
41d0: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
41e0: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
41f0: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4200: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4210: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4220: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4230: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
4240: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
4250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
4260: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
4270: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
4280: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
4290: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
42a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
42b0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
42c0: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
42d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
42e0: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
42f0: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4300: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4310: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4320: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4330: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
4340: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
4350: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
4360: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
4370: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
4390: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
43a0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
43b0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
43c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
43d0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
43e0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
43f0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4400: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4410: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4420: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4430: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
4440: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
4450: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
4460: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
4470: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
4480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4490: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
44a0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
44b0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
44c0: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
44d0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
44e0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
44f0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4520: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4530: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
4540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4550: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
4560: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
4570: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
4580: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
45a0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
45b0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
45c0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
45d0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
45e0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
45f0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4600: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4630: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4640: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4650: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4680: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4690: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
46a0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
46b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46c0: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
46d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
46e0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
46f0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4700: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4710: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4720: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4730: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4740: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4750: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4770: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4780: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4790: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72  DS: {extended er
47a0: 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e  ror code} {exten
47b0: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d  ded error codes}
47c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
47d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
47e0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72  ode} {extended r
47f0: 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a  esult codes}.**.
4800: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4810: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4820: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4830: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4840: 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a  of 26 integer.**
4850: 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65   [SQLITE_OK | re
4860: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f  sult codes].  Ho
4870: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63  wever, experienc
4880: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74  e has shown that
4890: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73   many of.** thes
48a0: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  e result codes a
48b0: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72  re too coarse-gr
48c0: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20  ained.  They do 
48d0: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a  not provide as.*
48e0: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69  * much informati
48f0: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d  on about problem
4900: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73  s as programmers
4910: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e   might like.  In
4920: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a   an effort to.**
4930: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e   address this, n
4940: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
4950: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e   SQLite (version
4960: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72   3.3.8 and later
4970: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
4980: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
4990: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
49a0: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
49b0: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
49c0: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
49d0: 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74   errors. The ext
49e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49f0: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f  es are enabled o
4a00: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e  r disabled.** on
4a10: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20   a per database 
4a20: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
4a30: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
4a40: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
4a50: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20  result_codes()] 
4a60: 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  API..**.** Some 
4a70: 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  of the available
4a80: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a90: 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65   codes are liste
4aa0: 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d  d here..** One m
4ab0: 61 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75  ay expect the nu
4ac0: 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64  mber of extended
4ad0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69   result codes wi
4ae0: 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20  ll be expand.** 
4af0: 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74  over time.  Soft
4b00: 77 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65  ware that uses e
4b10: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4b20: 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65  odes should expe
4b30: 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77  ct.** to see new
4b40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e   result codes in
4b50: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
4b60: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4b70: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20  * The SQLITE_OK 
4b80: 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c  result code will
4b90: 20 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64   never be extend
4ba0: 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77  ed.  It will alw
4bb0: 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c  ays.** be exactl
4bc0: 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69  y zero..*/.#defi
4bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4bf0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c00: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4c10: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4c20: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4c30: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4c40: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4c50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4c60: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4c70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c80: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4c90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
4cb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4cc0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
4cd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
4ce0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
4cf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
4d00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4d10: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
4d20: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
4d30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
4d40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4d50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
4d60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4d70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
4dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4dd0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
4de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4df0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
4e00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e10: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
4e20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e30: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
4e40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e50: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
4e60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e70: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
4e80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4e90: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
4ea0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4eb0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
4ec0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4ed0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
4ee0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ef0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
4f00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f10: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
4f20: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
4f30: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
4f40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f50: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
4f60: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f70: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
4f80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f90: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
4fa0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4fb0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
4fc0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4fd0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
4fe0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4ff0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5000: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5010: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5020: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5030: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5040: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5050: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
5060: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5070: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
5080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5090: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
50a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
50c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
50e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5100: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5110: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5120: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5130: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5140: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5150: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5160: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5170: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5180: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5190: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
51a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
51e0: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
51f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5210: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5220: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5230: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5240: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5250: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
5260: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
5270: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
5280: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5290: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
52a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
52b0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
52c0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
52d0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
52e0: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
52f0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5300: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
5310: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5320: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5330: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5340: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a  T | (2<<8))../*.
5350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5360: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5370: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5380: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5390: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
53a0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
53b0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
53c0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
53d0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
53e0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
53f0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5400: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5410: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5420: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5430: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5440: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5450: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5460: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5470: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5480: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5490: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
54a0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
54b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
54c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
54d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
54e0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
54f0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5500: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5510: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5520: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5530: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5540: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5550: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5560: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5570: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5580: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5590: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
55a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
55b0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
55c0: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
55d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
55e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5600: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5610: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5620: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5630: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5640: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5650: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
5660: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5670: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5680: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
5690: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
56a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
56b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
56c0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
56d0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
56e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
56f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
5700: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5710: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
5720: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5730: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
5740: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
5750: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
5760: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5770: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
5780: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
5790: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
57a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
57b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
57c0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
57d0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
57e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
57f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
5800: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
5810: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
5820: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5830: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5840: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
5850: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
5860: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
5870: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5880: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5890: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
58a0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
58b0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
58c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
58d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
58e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
58f0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
5900: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
5910: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5920: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5930: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
5940: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5950: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
5960: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
5970: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
5980: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5990: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
59a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
59b0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
59c0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
59d0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
59e0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
59f0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
5a00: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
5a10: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
5a20: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
5a30: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
5a40: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
5a50: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
5a60: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
5a70: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
5a80: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
5a90: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
5aa0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
5ab0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
5ac0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
5ad0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
5ae0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
5af0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
5b00: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
5b10: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
5b20: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
5b40: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
5b50: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
5b60: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
5b70: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
5b80: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
5b90: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
5ba0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
5bb0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
5bc0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
5bd0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
5be0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
5bf0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
5c00: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
5c10: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
5c20: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
5c30: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
5c40: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
5c50: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
5c60: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
5c70: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
5c80: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
5c90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
5ca0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
5cb0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
5cc0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
5cd0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
5ce0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
5cf0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
5d00: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
5d10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
5d20: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
5d30: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
5d40: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
5d50: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
5d60: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
5d70: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
5d80: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
5d90: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
5da0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
5db0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
5dc0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
5dd0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
5de0: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
5df0: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
5e00: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
5e10: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
5e20: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
5e30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5e40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5e60: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5e70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5e80: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
5e90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ea0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5eb0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20  _IOCAP_ATOMIC1K 
5ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5ed0: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65  00000004.#define
5ee0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5ef0: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20  OMIC2K          
5f00: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a       0x00000008.
5f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f20: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20  OCAP_ATOMIC4K   
5f30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f40: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53  000010.#define S
5f50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f60: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC8K            
5f70: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
5f80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5f90: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
5fa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5fb0: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0040.#define SQL
5fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5fd0: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  32K             
5fe0: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66   0x00000080.#def
5ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6000: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20  _ATOMIC64K      
6010: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
6020: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6030: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6040: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30  END            0
6050: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e  x00000200.#defin
6060: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6070: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20  EQUENTIAL       
6080: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
6090: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
60a0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
60b0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30  E_WHEN_OPEN  0x0
60c0: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20  0000800.#define 
60d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
60e0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
60f0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a      0x00001000..
6100: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6110: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6120: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6130: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6140: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6150: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6160: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6170: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6180: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6190: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
61a0: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
61b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
61c0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
61d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
61e0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
61f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6200: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6210: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6220: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6230: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6240: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6250: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6260: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6270: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6280: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6290: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
62a0: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
62b0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
62c0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
62d0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
62e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
62f0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6300: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6310: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6320: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6330: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6340: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6350: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6360: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6370: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6380: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6390: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
63a0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
63b0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
63c0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
63d0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
63e0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
63f0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6400: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6410: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6420: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6430: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6440: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6450: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6460: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6470: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6480: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6490: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
64a0: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
64b0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
64c0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
64d0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
64e0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
64f0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6500: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6510: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6520: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6530: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6540: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6550: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6560: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6570: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6580: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6590: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
65a0: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
65b0: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
65c0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
65d0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
65e0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
65f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6600: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6610: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
6620: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
6630: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
6640: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
6650: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
6660: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
6670: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
6680: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
6690: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
66a0: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
66b0: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
66c0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
66d0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
66e0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
66f0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
6700: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
6710: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
6720: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
6730: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
6740: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
6750: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
6760: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
6770: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
6780: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
6790: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
67a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
67b0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
67c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
67d0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
67e0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
67f0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
6800: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
6810: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
6820: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
6830: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
6840: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
6850: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6860: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
6870: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
6880: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
6890: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
68a0: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
68b0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
68c0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
68d0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
68e0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
68f0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
6900: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
6910: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
6920: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
6930: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
6940: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
6950: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
6960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6970: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
6980: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
6990: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
69a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
69b0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
69c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
69d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
69e0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
69f0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
6a00: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
6a10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6a20: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
6a30: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
6a40: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
6a50: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6a60: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
6a70: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
6a80: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
6a90: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
6aa0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
6ab0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6ac0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
6ad0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
6ae0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
6af0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
6b00: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
6b10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
6b20: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
6b30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
6b40: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
6b50: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
6b60: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
6b70: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
6b80: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
6b90: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
6ba0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
6bb0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
6bc0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
6bd0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
6be0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
6bf0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6c00: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
6c10: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
6c20: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
6c30: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
6c40: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
6c50: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
6c60: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
6c70: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
6c80: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
6c90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6ca0: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
6cb0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
6cc0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
6cd0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
6ce0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
6cf0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
6d00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6d10: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
6d20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
6d30: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
6d40: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6d50: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
6d60: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
6d70: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
6d80: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
6d90: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
6da0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
6db0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
6dc0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
6dd0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
6de0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
6df0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
6e00: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
6e10: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6e20: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
6e30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6e40: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6e50: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6e60: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6e70: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6e80: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6e90: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6ea0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6eb0: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6ec0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6ed0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6ee0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
6ef0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6f00: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
6f10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6f20: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6f30: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6f40: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6f50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6f60: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6f70: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6f80: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6f90: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6fa0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6fb0: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
6fc0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
6fd0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
6fe0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
6ff0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
7000: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
7010: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7020: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7030: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7040: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7050: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7060: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7070: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7080: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7090: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
70a0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
70b0: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
70c0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
70d0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
70e0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
70f0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7100: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7110: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7120: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7130: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7140: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7150: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7160: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7170: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7180: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7190: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
71a0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
71b0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
71c0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
71d0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
71e0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
71f0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7200: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7210: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7220: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7230: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7240: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7250: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7260: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7270: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7280: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7290: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
72a0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
72b0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
72c0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
72d0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
72e0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
72f0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7300: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7310: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7320: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7330: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7340: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7350: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7360: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7370: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7380: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
7390: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
73a0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
73b0: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
73c0: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
73d0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
73e0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
73f0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7400: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7410: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7420: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7430: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7440: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
7450: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7460: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
7470: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
7480: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7490: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
74a0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
74b0: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
74c0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
74d0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
74e0: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
74f0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
7500: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
7510: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
7520: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
7530: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
7540: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
7550: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
7560: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
7570: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
7580: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
7590: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
75a0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
75b0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
75c0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
75d0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
75e0: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
75f0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7600: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7610: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
7620: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7630: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
7640: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7650: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
7660: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7670: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
7680: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7690: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
76a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76b0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
76c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
76d0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
76e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76f0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
7700: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7710: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
7720: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7740: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7750: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7760: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
7770: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
7780: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
7790: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
77a0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
77b0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
77c0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
77d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
77e0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
77f0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
7800: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
7810: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
7820: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
7830: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
7840: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
7850: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
7860: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
7870: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
7880: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7890: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
78a0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
78b0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
78c0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
78d0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
78e0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
78f0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
7900: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
7910: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
7920: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
7930: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7940: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
7950: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
7960: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
7970: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
7980: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
7990: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
79a0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
79b0: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
79c0: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
79d0: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
79e0: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
79f0: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
7a00: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
7a10: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
7a20: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
7a30: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
7a40: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
7a50: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
7a60: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
7a70: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
7a80: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7a90: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
7aa0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
7ab0: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
7ac0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7ad0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7ae0: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
7af0: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
7b00: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7b10: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
7b20: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
7b30: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
7b40: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
7b50: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
7b60: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
7b70: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
7b80: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
7b90: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
7ba0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
7bb0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
7bc0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
7bd0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
7be0: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
7bf0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7c00: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
7c10: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
7c20: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7c30: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
7c40: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
7c50: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
7c60: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
7c70: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
7c80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7c90: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
7ca0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
7cb0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
7cc0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
7cd0: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
7ce0: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
7cf0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
7d00: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
7d10: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
7d20: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
7d30: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
7d40: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7d50: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
7d60: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
7d70: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
7d80: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
7d90: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
7da0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
7db0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
7dc0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7dd0: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
7de0: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
7df0: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
7e00: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
7e10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7e20: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
7e30: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
7e40: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
7e50: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7e60: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
7e70: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
7e80: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
7e90: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
7ea0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7eb0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
7ec0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
7ed0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7ee0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
7ef0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
7f00: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7f10: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
7f20: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
7f30: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7f40: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
7f50: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
7f60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7f70: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7f80: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7f90: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7fa0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7fb0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7fc0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
7fd0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7fe0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7ff0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8000: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8010: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8020: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8030: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8040: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8050: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8060: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8070: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8080: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8090: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
80a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
80b0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
80c0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
80d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
80e0: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
80f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8100: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8110: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8120: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8130: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8140: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8150: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8160: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8170: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8180: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8190: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
81a0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
81b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
81c0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
81d0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
81e0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
81f0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8200: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8210: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8220: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8230: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8240: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8250: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8260: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8270: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8280: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8290: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
82a0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
82b0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
82c0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
82d0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
82e0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
82f0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8300: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8310: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8320: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8330: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8340: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8350: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8360: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8370: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8380: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8390: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
83a0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
83b0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
83c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
83d0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
83e0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
83f0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8400: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8410: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8420: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8430: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8440: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8450: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8460: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8470: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8480: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8490: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
84a0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
84b0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
84c0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
84d0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
84e0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
84f0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8500: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8510: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8520: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8530: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
8540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
8550: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
8560: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8570: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
8580: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8590: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
85a0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
85b0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
85c0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
85d0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
85e0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
85f0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
8600: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8610: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
8620: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
8630: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
8640: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
8650: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8660: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
8670: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
8680: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
8690: 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  ED] opcode is ge
86a0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
86b0: 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20  ly by.** SQLite 
86c0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20  and sent to all 
86d0: 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  VFSes in place o
86e0: 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20  f a call to the 
86f0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20  xSync method.** 
8700: 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
8710: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73  e connection has
8720: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
8730: 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46  nous] set to OFF
8740: 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63  .)^.** Some spec
8750: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65  ialized VFSes ne
8760: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69  ed this signal i
8770: 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61  n order to opera
8780: 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20  te correctly.** 
8790: 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e  when [PRAGMA syn
87a0: 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d  chronous | PRAGM
87b0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46  A synchronous=OF
87c0: 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d  F] is set, but m
87d0: 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f  ost .** VFSes do
87e0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
87f0: 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64  ignal and should
8800: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
8810: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
8820: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
8830: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
8840: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8850: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
8860: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  .** opcode as do
8870: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
8880: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
8890: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
88a0: 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61  zed VFSes.** tha
88b0: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
88c0: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
88d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
88e0: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
88f0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
8900: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
8910: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
8920: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
8930: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
8940: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
8950: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
8960: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
8970: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
8980: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
8990: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
89a0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
89b0: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
89c0: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
89d0: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
89e0: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
89f0: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
8a00: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
8a10: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
8a20: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
8a30: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
8a40: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
8a50: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
8a60: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
8a70: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
8a80: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
8a90: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
8aa0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
8ab0: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
8ac0: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
8ad0: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
8ae0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
8af0: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
8b00: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
8b10: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
8b20: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
8b30: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
8b40: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
8b50: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
8b60: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
8b70: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
8b80: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
8b90: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
8ba0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
8bb0: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
8bc0: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
8bd0: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
8be0: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
8bf0: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
8c00: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
8c10: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
8c20: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
8c30: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
8c40: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
8c50: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
8c60: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
8c70: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
8c80: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
8c90: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
8ca0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
8cb0: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
8cc0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
8cd0: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
8ce0: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
8cf0: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
8d00: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
8d10: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
8d20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
8d30: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
8d40: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
8d50: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
8d60: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8d70: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
8d80: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
8d90: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48   [WAL | Write AH
8da0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
8db0: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8dc0: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
8dd0: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
8de0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
8df0: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
8e00: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
8e10: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
8e20: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
8e30: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
8e40: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
8e50: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
8e60: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
8e70: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
8e80: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
8e90: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
8ea0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
8eb0: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
8ec0: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
8ed0: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
8ee0: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
8ef0: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
8f00: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
8f10: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
8f20: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
8f30: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
8f40: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
8f50: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
8f60: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
8f70: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
8f80: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
8f90: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
8fa0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
8fb0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
8fc0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
8fd0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
8fe0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
8ff0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9000: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9010: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9020: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
9030: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
9040: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9050: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
9060: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
9070: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
9080: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
9090: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
90a0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
90b0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
90c0: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
90d0: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
90e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
90f0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9100: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
9110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
9120: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
9130: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9140: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9150: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9160: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
9170: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
9180: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
9190: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
91a0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
91b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
91c0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
91d0: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
91e0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
91f0: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
9200: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
9210: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
9220: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9230: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
9240: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
9250: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
9260: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
9270: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
9280: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
9290: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
92a0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
92b0: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
92c0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
92d0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
92e0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
92f0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
9300: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
9310: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
9320: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9330: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
9340: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9350: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
9360: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
9370: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
9380: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
9390: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
93a0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
93b0: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
93c0: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
93d0: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
93e0: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
93f0: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
9400: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
9410: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
9420: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
9430: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
9440: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
9450: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9460: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
9470: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9480: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
9490: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
94a0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
94b0: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
94c0: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
94d0: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
94e0: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
94f0: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
9500: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
9510: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
9520: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
9530: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
9540: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
9550: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
9560: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
9570: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
9580: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
9590: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
95a0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
95b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95c0: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
95d0: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
95e0: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
95f0: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
9600: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
9610: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
9620: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
9630: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
9640: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
9650: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
9660: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
9670: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
9680: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
9690: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
96a0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
96b0: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
96c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
96d0: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
96e0: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
96f0: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
9700: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
9710: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
9720: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9730: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
9740: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
9750: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
9760: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
9770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
9780: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
9790: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
97a0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
97b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
97c0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
97d0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
97e0: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
97f0: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
9800: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
9810: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
9820: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9830: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
9840: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
9850: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
9860: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
9870: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
9880: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
9890: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
98a0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
98b0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
98c0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
98d0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
98e0: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
98f0: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
9900: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
9910: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
9920: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
9930: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9940: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
9950: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
9960: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
9970: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
9980: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
9990: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
99a0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
99b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
99c0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
99d0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
99e0: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
99f0: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
9a00: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
9a10: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
9a20: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
9a30: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
9a40: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
9a50: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
9a60: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
9a70: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
9a80: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
9a90: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
9aa0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
9ab0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
9ac0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9ad0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
9ae0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
9af0: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
9b00: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
9b10: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
9b20: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
9b30: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
9b40: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
9b50: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
9b60: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
9b70: 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  atement.  ^If th
9b80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9b90: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9ba0: 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20  trol returns.** 
9bb0: 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20  any result code 
9bc0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
9bd0: 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54  TE_OK] or [SQLIT
9be0: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61  E_NOTFOUND], tha
9bf0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  t means.** that 
9c00: 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65  the VFS encounte
9c10: 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69  red an error whi
9c20: 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20  le handling the 
9c30: 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65  [PRAGMA] and the
9c40: 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  .** compilation 
9c50: 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61  of the PRAGMA fa
9c60: 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ils with an erro
9c70: 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  r.  ^The [SQLITE
9c80: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
9c90: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  * file control o
9ca0: 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67  ccurs at the beg
9cb0: 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61  inning of pragma
9cc0: 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79   statement analy
9cd0: 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74  sis and so.** it
9ce0: 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72   is able to over
9cf0: 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50  ride built-in [P
9d00: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
9d10: 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  s..** </ul>.*/.#
9d20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9d30: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
9d40: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
9d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
9d60: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
9d70: 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
9d80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
9d90: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
9da0: 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
9db0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
9dc0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
9dd0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
9de0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9df0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
9e00: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
9e10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
9e20: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
9e30: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
9e40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
9e50: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
9e60: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
9e70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9e80: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
9e90: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
9ea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9eb0: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
9ec0: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
9ed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9ee0: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
9ef0: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
9f00: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
9f10: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
9f20: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
9f30: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9f50: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
9f60: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9f70: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
9f80: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
9f90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
9fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
9fb0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9fc0: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
9fd0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
9fe0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
9ff0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
a000: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
a010: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
a020: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
a030: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
a040: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
a050: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
a060: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
a070: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
a080: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
a090: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
a0a0: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
a0b0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
a0c0: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
a0d0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
a0e0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
a0f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
a100: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
a110: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
a120: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
a130: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
a140: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
a150: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
a160: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
a170: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
a180: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
a190: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
a1a0: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
a1b0: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
a1c0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
a1d0: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
a1e0: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
a1f0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
a200: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
a210: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
a220: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
a230: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
a240: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
a250: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
a260: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
a270: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
a280: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
a290: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
a2a0: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
a2b0: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
a2c0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
a2d0: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
a2e0: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
a2f0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
a300: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
a310: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
a320: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
a330: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
a340: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
a350: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
a360: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
a370: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
a380: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
a390: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
a3a0: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
a3b0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
a3c0: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
a3d0: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
a3e0: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
a3f0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
a400: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
a410: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
a420: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
a430: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
a440: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
a450: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
a460: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
a470: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
a480: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
a490: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
a4a0: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
a4b0: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
a4c0: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
a4d0: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
a4e0: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
a4f0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
a500: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
a510: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
a520: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
a530: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
a540: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
a550: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
a560: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
a570: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
a580: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
a590: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
a5a0: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
a5b0: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
a5c0: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
a5d0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
a5e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
a5f0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
a600: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
a610: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
a620: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
a630: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
a640: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
a650: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
a660: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
a670: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
a680: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
a690: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
a6a0: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
a6b0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a6c0: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
a6d0: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
a6e0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
a6f0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
a700: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
a710: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
a720: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
a730: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
a740: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
a750: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
a760: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
a770: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
a780: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
a790: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
a7a0: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
a7b0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
a7c0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
a7d0: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
a7e0: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
a7f0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
a800: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
a810: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
a820: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
a830: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
a840: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
a850: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
a860: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a870: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
a880: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
a890: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
a8a0: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
a8b0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
a8c0: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
a8d0: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
a8e0: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
a8f0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
a900: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
a910: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
a920: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
a930: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
a940: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
a950: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
a960: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
a970: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
a980: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
a990: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
a9a0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
a9b0: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
a9c0: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
a9d0: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
a9e0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
a9f0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
aa00: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
aa10: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
aa20: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
aa30: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
aa40: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
aa50: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
aa60: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
aa70: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
aa80: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
aa90: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
aaa0: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
aab0: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
aac0: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
aad0: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
aae0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
aaf0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
ab00: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
ab10: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
ab20: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
ab30: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
ab40: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
ab50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
ab60: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
ab70: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
ab80: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
ab90: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
aba0: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
abb0: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
abc0: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
abd0: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
abe0: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
abf0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
ac00: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ac10: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
ac20: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ac30: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ac40: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ac50: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
ac60: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
ac70: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
ac80: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
ac90: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
aca0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
acb0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
acc0: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
acd0: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
ace0: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
acf0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
ad00: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
ad10: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
ad20: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
ad30: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
ad40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
ad50: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ad60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ad70: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ad80: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ad90: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ada0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
adb0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
adc0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
add0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ade0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
adf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
ae00: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ae10: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
ae20: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ae30: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
ae40: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
ae50: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
ae60: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
ae70: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
ae80: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
ae90: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
aea0: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
aeb0: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
aec0: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
aed0: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
aee0: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
aef0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
af00: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
af10: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
af20: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
af30: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
af40: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
af50: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
af60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
af70: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
af80: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
af90: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
afa0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
afb0: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
afc0: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
afd0: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
afe0: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
aff0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
b000: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
b010: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
b020: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
b030: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
b040: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
b050: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
b060: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
b070: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
b080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
b090: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
b0a0: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
b0b0: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
b0c0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
b0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
b0e0: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
b0f0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
b100: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
b110: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
b120: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
b130: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
b140: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
b150: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
b160: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
b170: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
b180: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
b190: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
b1a0: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
b1b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
b1c0: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
b1d0: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
b1e0: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
b1f0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
b200: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
b210: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
b220: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
b230: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
b240: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
b250: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
b260: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
b270: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
b280: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
b290: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
b2a0: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
b2b0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
b2c0: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
b2d0: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
b2e0: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
b2f0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
b300: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
b310: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
b320: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
b330: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
b340: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
b350: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
b360: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
b370: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
b380: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
b390: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
b3a0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
b3b0: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
b3c0: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
b3d0: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
b3e0: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
b3f0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
b400: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
b410: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
b420: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
b430: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
b440: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
b450: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
b460: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
b470: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
b480: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
b490: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
b4a0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
b4b0: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
b4c0: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
b4d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
b4e0: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
b4f0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
b500: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
b510: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
b520: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
b530: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
b540: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
b550: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
b560: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
b570: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
b580: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
b590: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
b5a0: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
b5b0: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
b5c0: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
b5d0: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
b5e0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
b5f0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
b600: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
b610: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
b620: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
b630: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
b640: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
b650: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
b660: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
b670: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
b680: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
b690: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
b6a0: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
b6b0: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
b6c0: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
b6d0: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
b6e0: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
b6f0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
b700: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
b710: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
b720: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
b730: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
b740: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
b750: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
b760: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
b770: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
b780: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
b790: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
b7a0: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
b7b0: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
b7c0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
b7d0: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
b7e0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
b7f0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
b800: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
b810: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
b820: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
b830: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
b840: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
b850: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
b860: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
b870: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
b880: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
b890: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
b8a0: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
b8b0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
b8c0: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
b8d0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
b8e0: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
b8f0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
b900: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
b910: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
b920: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
b930: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
b940: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
b950: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
b960: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
b970: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
b980: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
b990: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
b9a0: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
b9b0: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
b9c0: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
b9d0: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
b9e0: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
b9f0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
ba00: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
ba10: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
ba20: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
ba30: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
ba40: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
ba50: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
ba60: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
ba70: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
ba80: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
ba90: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
baa0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
bab0: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
bac0: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
bad0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
bae0: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
baf0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
bb00: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
bb10: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bb20: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
bb30: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
bb40: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
bb50: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
bb60: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
bb70: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
bb80: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
bb90: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
bba0: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
bbb0: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
bbc0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
bbd0: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
bbe0: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
bbf0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
bc00: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
bc10: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
bc20: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
bc30: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
bc40: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
bc50: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
bc60: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
bc70: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
bc80: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
bc90: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
bca0: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
bcb0: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
bcc0: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
bcd0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
bce0: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
bcf0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
bd00: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
bd10: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
bd20: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
bd30: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
bd40: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
bd50: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
bd60: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
bd70: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
bd80: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
bd90: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
bda0: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
bdb0: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
bdc0: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
bdd0: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
bde0: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
bdf0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
be00: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
be10: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
be20: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
be30: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
be40: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
be50: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
be60: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
be70: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
be80: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
be90: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
bea0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
beb0: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
bec0: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
bed0: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
bee0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
bef0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
bf00: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
bf10: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
bf20: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
bf30: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
bf40: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
bf50: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
bf60: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
bf70: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
bf80: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
bf90: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
bfa0: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
bfb0: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
bfc0: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
bfd0: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
bfe0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
bff0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
c000: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
c010: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
c020: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
c030: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
c040: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
c050: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
c060: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
c070: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
c080: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
c090: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
c0a0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
c0b0: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
c0c0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
c0d0: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
c0e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
c0f0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
c100: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
c110: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
c120: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
c130: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
c140: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
c150: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
c160: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
c170: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
c180: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
c190: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
c1a0: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
c1b0: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
c1c0: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
c1d0: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
c1e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
c1f0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
c200: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
c210: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
c220: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
c230: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
c240: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
c250: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c260: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
c270: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
c280: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
c290: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
c2a0: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
c2b0: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
c2c0: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
c2d0: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
c2e0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
c2f0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
c300: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
c310: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
c320: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c330: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
c340: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
c350: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
c360: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
c370: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
c380: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
c390: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
c3a0: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
c3b0: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
c3c0: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
c3d0: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
c3e0: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
c3f0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
c400: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
c410: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c420: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
c430: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
c440: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
c450: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
c460: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
c470: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
c480: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
c490: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
c4a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c4b0: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
c4c0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
c4d0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
c4e0: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
c4f0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
c500: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
c510: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
c520: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
c530: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
c540: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
c550: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
c560: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
c570: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
c580: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
c590: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
c5a0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
c5b0: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
c5c0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
c5d0: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
c5e0: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
c5f0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
c600: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
c610: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
c620: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c630: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c640: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
c650: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
c660: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
c670: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
c680: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
c690: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c6a0: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
c6b0: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
c6c0: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
c6d0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c6e0: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
c6f0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
c700: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
c710: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
c720: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
c730: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
c740: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
c750: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
c760: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
c770: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
c780: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
c790: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
c7a0: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
c7b0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
c7c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
c7d0: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
c7e0: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
c7f0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
c800: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
c810: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
c820: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
c830: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
c840: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
c850: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
c860: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
c870: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
c880: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
c890: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
c8a0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
c8b0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
c8c0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
c8d0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
c8e0: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
c8f0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
c900: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
c910: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c920: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
c930: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
c940: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
c950: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
c960: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
c970: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
c980: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
c990: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
c9a0: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
c9b0: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
c9c0: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
c9d0: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
c9e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c9f0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
ca00: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
ca10: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
ca20: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
ca30: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
ca40: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
ca50: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
ca60: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
ca70: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
ca80: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ca90: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
caa0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
cab0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
cac0: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
cad0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
cae0: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
caf0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
cb00: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
cb10: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
cb20: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
cb30: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
cb40: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
cb50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
cb60: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
cb70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
cb80: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
cb90: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
cba0: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
cbb0: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
cbc0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
cbd0: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
cbe0: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
cbf0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
cc00: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
cc10: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
cc20: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cc30: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
cc40: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
cc50: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
cc60: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
cc70: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
cc80: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
cc90: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
cca0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ccb0: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
ccc0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
ccd0: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
cce0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
ccf0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cd00: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
cd10: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
cd20: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
cd30: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
cd40: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
cd50: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
cd60: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
cd70: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
cd80: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
cd90: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
cda0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
cdb0: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
cdc0: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
cdd0: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
cde0: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
cdf0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
ce00: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
ce10: 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74  * was given no t
ce20: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
ce30: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
ce40: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
ce50: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ce60: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ce70: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ce80: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ce90: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
cea0: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ceb0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
cec0: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ced0: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
cee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
cef0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
cf00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
cf10: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
cf20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cf30: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
cf40: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
cf50: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
cf60: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
cf70: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
cf80: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
cf90: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
cfa0: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
cfb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
cfc0: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
cfd0: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
cfe0: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
cff0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
d000: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
d010: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
d020: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
d030: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
d040: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
d050: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
d060: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
d070: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
d080: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
d090: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
d0a0: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
d0b0: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
d0c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
d0d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
d0e0: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
d0f0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
d100: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
d110: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
d120: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
d130: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
d140: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
d150: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
d160: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d170: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
d180: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
d190: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
d1a0: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
d1b0: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
d1c0: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
d1d0: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
d1e0: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
d1f0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
d200: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
d210: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
d220: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
d230: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
d240: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
d250: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
d260: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
d270: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
d280: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
d290: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d2a0: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
d2b0: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
d2c0: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
d2d0: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
d2e0: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
d2f0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
d300: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
d310: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
d320: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
d330: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
d340: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
d350: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
d360: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d370: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
d380: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
d390: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
d3a0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
d3b0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
d3c0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
d3d0: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
d3e0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d3f0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
d400: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
d410: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d420: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
d430: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d440: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
d450: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
d460: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
d470: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
d480: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
d490: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
d4a0: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
d4b0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d4c0: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
d4d0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
d4e0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
d4f0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
d500: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
d510: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
d520: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
d530: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
d540: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
d550: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
d560: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
d570: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
d580: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
d590: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d5a0: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
d5b0: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
d5c0: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
d5d0: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
d5e0: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
d5f0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
d600: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d610: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
d620: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
d630: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d640: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
d650: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
d660: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
d670: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
d680: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
d690: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
d6a0: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
d6b0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d6c0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
d6d0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
d6e0: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
d6f0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
d700: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
d710: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
d720: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
d730: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
d740: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
d750: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
d760: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
d770: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
d780: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
d790: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
d7a0: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
d7b0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
d7c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
d7d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
d7e0: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
d7f0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
d800: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
d810: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
d820: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
d830: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
d840: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
d850: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
d860: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
d870: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
d880: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
d890: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
d8a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d8b0: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
d8c0: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
d8d0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
d8e0: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
d8f0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
d900: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
d910: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
d920: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
d930: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
d940: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
d950: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
d960: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
d970: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
d980: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
d990: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
d9a0: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
d9b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d9c0: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
d9d0: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
d9e0: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
d9f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
da00: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
da10: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
da20: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
da30: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
da40: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
da50: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
da60: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
da70: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
da80: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
da90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
daa0: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
dab0: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
dac0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
dad0: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
dae0: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
daf0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
db00: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
db10: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
db20: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
db30: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
db40: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
db50: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
db60: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
db70: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
db80: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
db90: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
dba0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
dbb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
dbc0: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
dbd0: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
dbe0: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
dbf0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
dc00: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
dc10: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
dc20: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
dc30: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
dc40: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
dc50: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
dc60: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
dc70: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
dc80: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
dc90: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
dca0: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
dcb0: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
dcc0: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
dcd0: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
dce0: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
dcf0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
dd00: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
dd10: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
dd20: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
dd30: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
dd40: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
dd50: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
dd60: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
dd70: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
dd80: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
dd90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dda0: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
ddb0: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
ddc0: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
ddd0: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
dde0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
ddf0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
de00: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
de10: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
de20: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
de30: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
de40: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
de50: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
de60: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
de70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
de80: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
de90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
dea0: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
deb0: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
dec0: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ded0: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
dee0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
def0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
df00: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
df10: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
df20: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
df30: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
df40: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
df50: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
df60: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
df70: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
df80: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
df90: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
dfa0: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
dfb0: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
dfc0: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
dfd0: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
dfe0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
dff0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
e000: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
e010: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
e020: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
e030: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
e040: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
e050: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
e060: 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
e070: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
e080: 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
e090: 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
e0a0: 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
e0b0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
e0c0: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e0d0: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c  alize(void);.SQL
e0e0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
e0f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69  te3_shutdown(voi
e100: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
e110: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
e120: 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  it(void);.SQLITE
e130: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
e140: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
e150: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e160: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
e170: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
e180: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e190: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
e1a0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
e1b0: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
e1c0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
e1d0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
e1e0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
e1f0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
e200: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
e210: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
e220: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
e230: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
e240: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
e250: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
e260: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
e270: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
e280: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
e290: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
e2a0: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
e2b0: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
e2c0: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
e2d0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
e2e0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
e2f0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
e300: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
e310: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e320: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
e330: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
e340: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
e350: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
e360: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
e370: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
e380: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
e390: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
e3a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e3b0: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
e3c0: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
e3d0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
e3e0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
e3f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
e400: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
e410: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
e420: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e430: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
e440: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
e450: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
e460: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e470: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
e480: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
e490: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
e4a0: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
e4b0: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
e4c0: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
e4d0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
e4e0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
e4f0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
e500: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
e510: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
e520: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
e530: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
e540: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
e550: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
e560: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
e570: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63  an integer.** [c
e580: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e590: 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d  ion] that determ
e5a0: 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f  ines.** what pro
e5b0: 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20  perty of SQLite 
e5c0: 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75  is to be configu
e5d0: 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74  red.  Subsequent
e5e0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61   arguments.** va
e5f0: 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
e600: 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  the [configurati
e610: 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e  on option].** in
e620: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
e630: 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ent..**.** ^When
e640: 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   a configuration
e650: 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20   option is set, 
e660: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e670: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
e680: 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  _OK]..** ^If the
e690: 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f   option is unkno
e6a0: 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20  wn or SQLite is 
e6b0: 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68  unable to set th
e6c0: 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e  e option.** then
e6d0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
e6e0: 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f  turns a non-zero
e6f0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
e700: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
e710: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e720: 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
e730: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
e740: 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
e750: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  onnections.**.**
e760: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
e770: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e780: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e790: 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
e7a0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
e7b0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e7c0: 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
e7d0: 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
e7e0: 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
e7f0: 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
e800: 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
e810: 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
e820: 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
e830: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
e840: 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
e850: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
e860: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
e870: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
e880: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e890: 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
e8a0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
e8b0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
e8c0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
e8d0: 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
e8e0: 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
e8f0: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
e900: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
e910: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e920: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
e930: 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
e940: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
e950: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
e960: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
e970: 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
e980: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
e990: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
e9a0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
e9b0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
e9c0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
e9d0: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
e9e0: 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
e9f0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  I int sqlite3_db
ea00: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
ea10: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
ea20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ea30: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
ea40: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
ea50: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
ea60: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
ea70: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
ea80: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
ea90: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
eaa0: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
eab0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
eac0: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
ead0: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
eae0: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
eaf0: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
eb00: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
eb10: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
eb20: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
eb30: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
eb40: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
eb50: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
eb60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
eb70: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
eb80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
eb90: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
eba0: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
ebb0: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
ebc0: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
ebd0: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
ebe0: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
ebf0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
ec00: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
ec10: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
ec20: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
ec30: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
ec40: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
ec50: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
ec60: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ec70: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
ec80: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
ec90: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
eca0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
ecb0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
ecc0: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
ecd0: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
ece0: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
ecf0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
ed00: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
ed10: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
ed20: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
ed30: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
ed40: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
ed50: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
ed60: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
ed70: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
ed80: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
ed90: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
eda0: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
edb0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
edc0: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
edd0: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
ede0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
edf0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
ee00: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
ee10: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
ee20: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
ee30: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
ee40: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
ee50: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
ee60: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
ee70: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
ee80: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
ee90: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
eea0: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
eeb0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
eec0: 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
eed0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
eee0: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
eef0: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
ef00: 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
ef10: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
ef20: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
ef30: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
ef40: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
ef50: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
ef60: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ef70: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
ef80: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
ef90: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
efa0: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
efb0: 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
efc0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
efd0: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
efe0: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
eff0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
f000: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
f010: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
f020: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
f030: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
f040: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
f050: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
f060: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
f070: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
f080: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
f090: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
f0a0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
f0b0: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
f0c0: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
f0d0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f0e0: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
f0f0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
f100: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
f110: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
f120: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
f130: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
f140: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
f150: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
f160: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
f170: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
f180: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
f190: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
f1a0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
f1b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f1c0: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
f1d0: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
f1e0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
f1f0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
f200: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
f210: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
f220: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
f230: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
f240: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
f250: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
f260: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
f270: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
f280: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
f290: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
f2a0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
f2b0: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
f2c0: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
f2d0: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
f2e0: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
f2f0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
f300: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
f310: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
f320: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
f330: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
f340: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
f350: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
f360: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
f370: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
f380: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
f390: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
f3a0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
f3b0: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
f3c0: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
f3d0: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
f3e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
f3f0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
f400: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
f410: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
f420: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
f430: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
f440: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
f450: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
f460: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
f470: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
f480: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
f490: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
f4a0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
f4b0: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
f4c0: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
f4d0: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
f4e0: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
f4f0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
f500: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
f510: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
f520: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
f530: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
f540: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
f550: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
f560: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
f570: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
f580: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
f590: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
f5a0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
f5b0: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
f5c0: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
f5d0: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
f5e0: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
f5f0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
f600: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
f610: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
f620: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
f630: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
f640: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
f650: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
f660: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
f670: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
f680: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
f690: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
f6a0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
f6b0: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
f6c0: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
f6d0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
f6e0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
f6f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
f700: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
f710: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
f720: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
f730: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
f740: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
f750: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
f760: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
f770: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
f780: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
f790: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
f7a0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
f7b0: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
f7c0: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
f7d0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
f7e0: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
f7f0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
f800: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
f810: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
f820: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
f830: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
f840: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
f850: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
f860: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
f870: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
f880: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
f890: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
f8a0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
f8b0: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
f8c0: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
f8d0: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
f8e0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
f8f0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f900: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
f910: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
f920: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
f930: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
f940: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
f950: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f960: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
f970: 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
f980: 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
f990: 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
f9a0: 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
f9b0: 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
f9c0: 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
f9d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f9e0: 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
f9f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
fa00: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
fa10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
fa20: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
fa30: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
fa40: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fa50: 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
fa60: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
fa70: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
fa80: 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
fa90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
faa0: 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
fab0: 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
fac0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
fad0: 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
fae0: 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
faf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
fb00: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
fb10: 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
fb20: 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
fb30: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
fb40: 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
fb50: 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
fb60: 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
fb70: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
fb80: 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
fb90: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
fba0: 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
fbb0: 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
fbc0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
fbd0: 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
fbe0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
fbf0: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
fc00: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
fc10: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
fc20: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
fc30: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
fc40: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
fc50: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
fc60: 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
fc70: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
fc80: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
fc90: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
fca0: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
fcb0: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
fcc0: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
fcd0: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
fce0: 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
fcf0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
fd00: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
fd10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
fd20: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
fd30: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
fd40: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
fd50: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
fd60: 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
fd70: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
fd80: 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
fd90: 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
fda0: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
fdb0: 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
fdc0: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
fdd0: 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
fde0: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
fdf0: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
fe00: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fe10: 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
fe20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
fe30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
fe40: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
fe50: 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
fe60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
fe70: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fe80: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fe90: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fea0: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
feb0: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
fec0: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
fed0: 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
fee0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
fef0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
ff00: 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
ff10: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ff20: 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
ff30: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
ff40: 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
ff50: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
ff60: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
ff70: 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
ff80: 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
ff90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
ffa0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
ffb0: 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
ffc0: 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
ffd0: 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
ffe0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
fff0: 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
10000 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
10010 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
10020 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
10030 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
10040 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
10050 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
10060 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
10070 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
10080 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
10090 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
100a0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
100b0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
100c0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
100d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
100e0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
100f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
10100 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
10110 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
10120 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
10130 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10140 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
10150 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
10160 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
10170 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
10180 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
10190 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
101a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
101b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
101c0 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
101d0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
101e0 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
101f0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10200 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
10210 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
10220 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
10230 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
10240 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
10250 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
10260 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
10270 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
10280 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
10290 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
102a0 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
102b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
102c0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
102d0 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
102e0 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
102f0 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
10300 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
10310 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
10320 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
10330 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
10340 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
10350 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
10360 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
10370 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
10380 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
10390 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
103a0 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
103b0 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
103c0 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
103d0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
103e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
103f0 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
10400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
10410 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
10420 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
10430 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
10440 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10450 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10460 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10470 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10480 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10490 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
104a0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
104b0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
104c0 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
104d0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
104e0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
104f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
10500 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
10510 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
10520 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
10530 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
10540 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
10550 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
10560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
10570 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
10580 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10590 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
105a0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
105b0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
105c0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
105d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
105e0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
105f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10600 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10610 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
10620 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
10630 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
10640 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
10650 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10660 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
10670 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
10680 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10690 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
106a0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
106b0 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
106c0 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
106d0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
106e0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
106f0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10700 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
10710 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
10720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
10730 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
10740 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10750 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
10760 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
10770 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
10780 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10790 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
107a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
107b0 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
107c0 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
107d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
107e0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
107f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
10800 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
10810 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
10820 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
10830 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
10840 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
10850 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10860 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
10870 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
10880 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
10890 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
108a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
108b0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
108c0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
108d0 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
108e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
108f0 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
10900 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
10910 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
10920 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10930 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10940 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
10950 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10960 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
10970 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10980 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
10990 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69  t of type int, i
109a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
109b0 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  .** boolean, whi
109c0 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ch enables or di
109d0 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65  sables the colle
109e0 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20  ction of memory 
109f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73  allocation .** s
10a00 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
10a10 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10a20 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
10a30 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  re disabled, the
10a40 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   .** following S
10a50 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10a60 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72   become non-oper
10a70 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75  ational:.**   <u
10a80 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  l>.**   <li> [sq
10a90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
10aa0 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  d()].**   <li> [
10ab0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
10ac0 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20  ighwater()].**  
10ad0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
10ae0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
10af0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
10b00 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d  qlite3_status()]
10b10 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  .**   </ul>)^.**
10b20 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74   ^Memory allocat
10b30 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
10b40 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
10b50 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c  fault unless SQL
10b60 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ite is.** compil
10b70 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10b80 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
10b90 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61  S]=0 in which ca
10ba0 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  se memory.** all
10bb0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
10bc0 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  cs are disabled 
10bd0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c  by default..** <
10be0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
10bf0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
10c00 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  CH]] <dt>SQLITE_
10c10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
10c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
10c30 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
10c40 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
10c50 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
10c60 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
10c70 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  r.** scratch mem
10c80 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20  ory.  There are 
10c90 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
10ca0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
10cb0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
10cc0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
10cd0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
10ce0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10cf0 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
10d00 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
10d10 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
10d20 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
10d30 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
10d40 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
10d50 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
10d60 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61  N).  The sz.** a
10d70 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10d80 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36  a multiple of 16
10d90 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
10da0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10db0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
10dc0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
10dd0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
10de0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
10df0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
10e00 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e  QLite will use n
10e10 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20  o more than two 
10e20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20  scratch buffers 
10e30 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a  per thread.  So.
10e40 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73  ** N should be s
10e50 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20  et to twice the 
10e60 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d  expected maximum
10e70 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61   number of threa
10e80 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ds..** ^SQLite w
10e90 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72  ill never requir
10ea0 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66  e a scratch buff
10eb0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20  er that is more 
10ec0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20  than 6.** times 
10ed0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
10ee0 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69  e size. ^If SQLi
10ef0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
10f00 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
10f10 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
10f20 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
10f30 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
10f40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f50 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
10f60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
10f70 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
10f80 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
10f90 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  needed.</dd>.**.
10fa0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10fb0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
10fc0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10fd0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
10fe0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
10ff0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
11000 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
11010 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
11020 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
11030 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
11040 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
11050 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
11060 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
11070 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63  ion.  .** This c
11080 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f  onfiguration sho
11090 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
110a0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
110b0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
110c0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
110d0 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
110e0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  using the SQLITE
110f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
11100 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65  option..** There
11110 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
11120 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11130 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  ion: A pointer t
11140 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  o 8-byte aligned
11150 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20  .** memory, the 
11160 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
11170 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61  e buffer (sz), a
11180 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
11190 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   pages (N)..** T
111a0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
111b0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
111c0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
111d0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
111e0 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
111f0 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
11200 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20  d 32768) plus a 
11210 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72  little extra for
11220 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
11230 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65  ader.  ^The page
11240 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20   header size is 
11250 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64  20 to 40 bytes d
11260 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74  epending on.** t
11270 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63  he host architec
11280 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61  ture.  ^It is ha
11290 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
112a0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
112b0 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65  mory,.** to make
112c0 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f   sz a little too
112d0 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72   large.  The fir
112e0 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  st.** argument s
112f0 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61  hould point to a
11300 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20  n allocation of 
11310 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
11320 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
11330 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
11340 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
11350 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
11360 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11370 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
11380 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
11390 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
113a0 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
113b0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
113c0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
113d0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
113e0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
113f0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
11400 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
11410 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
11420 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
11430 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
11440 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
11450 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54  rage space..** T
11460 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68  he pointer in th
11470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11480 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67   must.** be alig
11490 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
114a0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
114b0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
114c0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69   of SQLite.** wi
114d0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
114e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
114f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
11500 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11510 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
11520 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
11530 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11540 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
11550 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
11560 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72   will use.** for
11570 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
11580 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
11590 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f  ation needs beyo
115a0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
115b0 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c  d.** for by [SQL
115c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
115d0 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  CH] and [SQLITE_
115e0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
115f0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  ]..** There are 
11600 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a  three arguments:
11610 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   An 8-byte align
11620 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  ed pointer to th
11630 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65  e memory,.** the
11640 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
11650 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62   in the memory b
11660 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d  uffer, and the m
11670 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
11680 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74  n size..** ^If t
11690 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
116a0 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
116b0 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74  nter) is NULL, t
116c0 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72  hen SQLite rever
116d0 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69  ts.** to using i
116e0 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  ts default memor
116f0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65  y allocator (the
11700 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
11710 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29   implementation)
11720 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79  ,.** undoing any
11730 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f   prior invocatio
11740 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  n of [SQLITE_CON
11750 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49  FIG_MALLOC].  ^I
11760 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  f the.** memory 
11770 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
11780 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b  ULL and either [
11790 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
117a0 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51  MSYS3] or.** [SQ
117b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
117c0 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64  YS5] are defined
117d0 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72  , then the alter
117e0 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a  native memory.**
117f0 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e   allocator is en
11800 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20  gaged to handle 
11810 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d  all of SQLites m
11820 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11830 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66   needs..** The f
11840 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
11850 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
11860 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  ) must be aligne
11870 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a  d to an 8-byte.*
11880 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  * boundary or su
11890 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
118a0 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  r of SQLite will
118b0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   be undefined..*
118c0 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  * The minimum al
118d0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73  location size is
118e0 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32   capped at 2**12
118f0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
11900 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
11910 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
11920 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20  n size are 2**5 
11930 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64  through 2**8.</d
11940 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11950 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d  E_CONFIG_MUTEX]]
11960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11970 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  IG_MUTEX</dt>.**
11980 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11990 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
119a0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
119b0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
119c0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
119d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
119e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
119f0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
11a00 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
11a10 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
11a20 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65  e low-level mute
11a30 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  x routines to be
11a40 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a   used in place.*
11a50 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74  * the mutex rout
11a60 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
11a70 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69  SQLite.)^  ^SQLi
11a80 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
11a90 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e  of the.** conten
11aa0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
11ab0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
11ac0 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72   structure befor
11ad0 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  e the call to.**
11ae0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11af0 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66  ()] returns. ^If
11b00 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
11b10 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
11b20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
11b30 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
11b40 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
11b50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
11b60 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
11b70 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
11b80 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
11b90 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
11ba0 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
11bb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11bc0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
11bd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
11be0 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
11bf0 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
11c00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11c10 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
11c20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11c30 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64  IG_GETMUTEX]] <d
11c40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c50 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a  GETMUTEX</dt>.**
11c60 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11c70 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11c80 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11c90 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11ca0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11cb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11cc0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
11cd0 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
11ce0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
11cf0 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
11d00 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
11d10 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
11d20 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
11d30 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
11d40 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
11d50 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
11d60 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
11d70 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
11d80 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
11d90 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
11da0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
11db0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
11dc0 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
11dd0 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
11de0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
11df0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
11e00 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
11e10 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
11e20 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
11e30 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
11e40 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
11e50 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
11e60 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
11e70 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
11e80 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
11e90 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
11ea0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
11eb0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
11ec0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11ed0 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
11ee0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
11ef0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
11f00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
11f10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11f20 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
11f30 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
11f40 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11f50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
11f60 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
11f70 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
11f80 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
11f90 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
11fa0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11fb0 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
11fc0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
11fd0 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
11fe0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11ff0 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
12000 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
12010 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
12020 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
12030 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
12040 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
12050 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
12060 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
12070 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12080 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
12090 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
120a0 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
120b0 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
120c0 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
120d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
120e0 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
120f0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12100 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
12110 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
12120 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
12130 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
12140 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
12150 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
12160 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12170 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  _PCACHE2]] <dt>S
12180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12190 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHE2</dt>.** <dd
121a0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
121b0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
121c0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
121d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
121e0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
121f0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
12200 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
12210 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  ct specifies the
12220 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
12230 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
12240 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
12250 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ion.)^  ^SQLite 
12260 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12270 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e  the.** object an
12280 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61  d uses it for pa
12290 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
122a0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64  allocations.</dd
122b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
122c0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
122d0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
122e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
122f0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
12300 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12310 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12320 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12330 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
12340 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
12350 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
12360 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
12370 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
12380 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
12390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
123a0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
123b0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
123c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
123d0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
123e0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
123f0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12400 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
12410 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
12420 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
12430 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
12440 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
12450 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
12460 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
12470 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
12480 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
12490 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
124a0 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
124b0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
124c0 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
124d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
124e0 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
124f0 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
12500 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
12510 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
12520 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
12530 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
12540 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
12550 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
12560 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
12570 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
12580 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
12590 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
125a0 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
125b0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
125c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
125d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
125e0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
125f0 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
12600 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
12610 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
12620 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
12630 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
12640 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
12650 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
12660 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
12670 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
12680 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
12690 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
126a0 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
126b0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
126c0 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
126d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
126e0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
126f0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
12700 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
12710 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
12720 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
12730 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
12740 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
12750 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
12760 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
12770 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
12780 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
12790 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
127a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
127b0 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
127c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
127d0 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
127e0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
127f0 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
12800 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
12810 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
12820 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
12830 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
12840 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12850 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
12860 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
12870 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f   <dd> This optio
12880 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12890 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
128a0 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65  e int. If non-ze
128b0 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20  ro, then.** URI 
128c0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
128d0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
128e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
128f0 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49  s zero, then URI
12900 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20   handling.** is 
12910 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
12920 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69  d. If URI handli
12930 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
12940 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
12950 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20  names.** passed 
12960 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
12970 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
12980 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  en_v2()], [sqlit
12990 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
129a0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
129b0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
129c0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
129d0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
129e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
129f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
12a00 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
12a10 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
12a20 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
12a30 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
12a40 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
12a50 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
12a60 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
12a70 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
12a80 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
12a90 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
12aa0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
12ab0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
12ac0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
12ad0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
12ae0 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20  ed. By default, 
12af0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
12b00 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
12b10 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
12b20 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
12b30 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
12b40 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
12b50 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
12b60 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
12b70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12b80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
12b90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12ba0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
12bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12bc0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
12bd0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
12be0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
12bf0 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
12c00 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
12c10 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
12c20 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
12c30 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
12c40 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
12c50 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
12c60 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
12c70 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
12c80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12c90 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
12ca0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
12cb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12cc0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
12cd0 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
12ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12cf0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
12d00 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
12d10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12d20 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
12d30 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
12d40 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
12d50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12d60 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12d70 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
12d80 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
12d90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12da0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12db0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
12dc0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
12dd0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
12de0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
12df0 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
12e00 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
12e10 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
12e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12e30 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
12e40 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
12e50 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
12e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12e70 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
12e80 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
12e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12ea0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
12eb0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
12ec0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
12ed0 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
12ee0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12ef0 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
12f00 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
12f10 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
12f20 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
12f30 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
12f40 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
12f50 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
12f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12f70 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
12f80 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
12f90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12fa0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
12fb0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
12fc0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
12fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12fe0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
12ff0 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
13000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13010 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
13020 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
13030 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13040 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
13050 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
13060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
13070 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13080 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
13090 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
130a0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
130b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
130c0 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
130d0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
130e0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
130f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
13100 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
13110 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
13120 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
13130 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
13140 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
13150 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
13160 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13170 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
13180 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
13190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
131a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
131b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
131c0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
131d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
131e0 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
131f0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
13200 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
13210 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
13220 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13230 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
13240 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
13250 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
13260 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
13270 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
13280 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13290 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
132a0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
132b0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
132c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
132d0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
132e0 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
132f0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
13300 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
13310 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
13320 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
13330 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
13340 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
13350 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
13360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
13370 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
13380 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13390 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
133a0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
133b0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
133c0 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
133d0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
133e0 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
133f0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
13400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13410 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
13420 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
13430 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
13440 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
13450 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
13460 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
13470 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
13480 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
13490 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
134a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
134b0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
134c0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
134d0 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
134e0 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
134f0 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
13500 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
13510 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
13520 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
13530 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13540 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
13550 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13560 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13570 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
13580 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
13590 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
135a0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
135b0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
135c0 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
135d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
135e0 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
135f0 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
13600 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
13610 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
13620 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
13630 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
13640 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
13650 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
13660 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
13670 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
13680 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
13690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
136a0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
136b0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
136c0 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
136d0 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
136e0 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
136f0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
13700 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
13710 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
13720 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
13730 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13740 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
13750 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
13760 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
13770 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
13780 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
13790 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
137a0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
137b0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
137c0 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
137d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
137e0 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
137f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13800 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
13810 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
13820 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
13830 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13840 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
13850 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
13860 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
13870 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
13880 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
13890 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
138a0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
138b0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
138c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
138d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
138e0 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
138f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
13900 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
13910 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
13920 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
13930 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
13940 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
13950 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
13960 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
13970 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
13980 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
13990 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
139a0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
139b0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
139c0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
139d0 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
139e0 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
139f0 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
13a00 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
13a10 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
13a20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
13a30 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13a40 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
13a50 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
13a60 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
13a70 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
13a80 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
13a90 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
13aa0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
13ab0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13ac0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
13ad0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
13ae0 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
13af0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
13b00 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13b10 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13b20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
13b30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
13b40 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
13b50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
13b60 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
13b70 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
13b80 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
13b90 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
13ba0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
13bb0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
13bc0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
13bd0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13be0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
13bf0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
13c00 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
13c10 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
13c20 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
13c30 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
13c40 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
13c50 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
13c60 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13c70 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13c80 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
13c90 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
13ca0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
13cb0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
13cc0 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
13cd0 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
13ce0 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
13cf0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
13d00 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13d10 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
13d20 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
13d30 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
13d40 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
13d50 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
13d60 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
13d70 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
13d80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
13d90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
13da0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
13db0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
13dc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
13dd0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
13de0 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
13df0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
13e00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
13e10 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
13e20 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
13e30 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
13e40 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
13e50 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
13e60 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
13e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
13e80 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
13e90 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
13ea0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
13eb0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
13ec0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
13ed0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
13ee0 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
13ef0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
13f00 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
13f10 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
13f20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
13f30 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
13f40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13f50 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
13f60 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
13f70 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
13f80 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
13f90 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
13fa0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
13fb0 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
13fc0 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
13fd0 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
13fe0 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
13ff0 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
14000 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
14010 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
14020 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
14030 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
14040 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
14050 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
14060 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
14070 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
14080 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
14090 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
140a0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
140b0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
140c0 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
140d0 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
140e0 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
140f0 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
14100 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
14110 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
14120 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
14130 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
14140 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
14150 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
14160 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
14170 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
14180 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
14190 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
141a0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
141b0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
141c0 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
141d0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
141e0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
141f0 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
14200 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
14210 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
14220 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
14230 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
14240 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
14250 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
14260 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
14270 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
14280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
14290 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
142a0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
142b0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
142c0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
142d0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
142e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
142f0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
14300 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
14310 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
14320 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
14330 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
14340 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
14350 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
14360 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
14370 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
14380 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
14390 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
143a0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
143b0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
143c0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
143d0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
143e0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
143f0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
14400 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
14410 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
14420 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
14430 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
14440 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
14450 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
14460 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
14470 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
14480 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
14490 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
144a0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
144b0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
144c0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
144d0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
144e0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
144f0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
14500 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
14510 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
14520 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
14530 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
14540 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
14550 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
14560 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
14570 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
14580 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
14590 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
145a0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
145b0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
145c0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
145d0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
145e0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
145f0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
14600 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
14610 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
14620 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
14630 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
14640 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
14650 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
14660 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
14670 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
14680 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
14690 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
146a0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
146b0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
146c0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
146d0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
146e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
146f0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
14700 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
14710 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
14720 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
14730 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
14740 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
14750 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
14760 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
14770 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
14780 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
14790 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
147a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
147b0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
147c0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
147d0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
147e0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
147f0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
14800 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
14810 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
14820 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
14830 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
14840 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
14850 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
14860 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
14870 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
14880 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
14890 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
148a0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
148b0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
148c0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
148d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
148e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
148f0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
14900 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
14910 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
14920 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
14930 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
14940 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
14950 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
14960 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
14970 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
14980 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
14990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
149a0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
149b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
149c0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
149d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
149e0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
149f0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
14a00 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
14a10 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
14a20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
14a30 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
14a40 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
14a50 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
14a60 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
14a70 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
14a80 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
14a90 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
14aa0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
14ab0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
14ac0 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
14ad0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
14ae0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
14af0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
14b00 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
14b10 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
14b20 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
14b30 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
14b40 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
14b50 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
14b60 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
14b70 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
14b80 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
14b90 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
14ba0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
14bb0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
14bc0 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
14bd0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
14be0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
14bf0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
14c00 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
14c10 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
14c20 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
14c30 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
14c40 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
14c50 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
14c60 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
14c70 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
14c80 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
14c90 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
14ca0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
14cb0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
14cc0 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
14cd0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
14ce0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
14cf0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
14d00 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
14d10 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
14d20 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
14d30 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
14d40 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
14d50 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
14d60 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
14d70 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
14d80 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
14d90 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
14da0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
14db0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
14dc0 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
14dd0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
14de0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
14df0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
14e00 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
14e10 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
14e20 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
14e30 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
14e40 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
14e50 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
14e60 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
14e70 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
14e80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
14e90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
14ea0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
14eb0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
14ec0 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
14ed0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
14ee0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
14ef0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
14f00 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
14f10 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
14f20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
14f30 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
14f40 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
14f50 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
14f60 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
14f70 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
14f80 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
14f90 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
14fa0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
14fb0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
14fc0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14fd0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
14fe0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
14ff0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
15000 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
15010 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
15020 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
15030 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
15040 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
15050 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
15060 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
15070 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
15080 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
15090 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
150a0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
150b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
150c0 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
150d0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
150e0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
150f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
15100 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
15110 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
15120 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
15130 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
15140 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
15150 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
15160 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
15170 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
15180 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
15190 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
151a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
151b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
151c0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
151d0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
151e0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
151f0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
15200 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
15210 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
15220 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
15230 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
15240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15250 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
15260 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
15270 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15280 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
15290 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
152a0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
152b0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
152c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
152d0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
152e0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
152f0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
15300 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
15310 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
15320 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
15330 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
15340 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
15350 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
15360 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
15370 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
15380 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
15390 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
153a0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
153b0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
153c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
153d0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
153e0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
153f0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
15400 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
15410 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
15420 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
15430 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
15440 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
15450 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
15460 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
15470 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
15480 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
15490 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
154a0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
154b0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
154c0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
154d0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
154e0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
154f0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
15500 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
15510 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
15520 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
15530 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
15540 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
15550 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
15560 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
15570 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
15580 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
15590 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
155a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
155b0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
155c0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
155d0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
155e0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
155f0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
15600 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
15610 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
15620 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
15630 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
15640 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
15650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
15660 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
15670 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
15680 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
15690 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
156a0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
156b0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
156c0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
156d0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
156e0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
156f0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
15700 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
15710 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
15720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
15730 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
15740 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
15750 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15760 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
15770 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
15780 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
15790 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
157a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
157b0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
157c0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
157d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
157e0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
157f0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
15800 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
15810 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
15820 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
15830 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
15840 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
15850 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
15860 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
15870 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
15880 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
15890 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
158a0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
158b0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
158c0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
158d0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
158e0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
158f0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
15900 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
15910 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
15920 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
15930 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
15940 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
15950 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
15960 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
15970 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
15980 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
15990 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
159a0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
159b0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
159c0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
159d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
159e0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
159f0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
15a00 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
15a10 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
15a20 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
15a30 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
15a40 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
15a50 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
15a60 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
15a70 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
15a80 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
15a90 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
15aa0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
15ab0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
15ac0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
15ad0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
15ae0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
15af0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
15b00 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
15b10 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
15b20 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
15b30 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
15b40 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
15b50 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
15b60 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
15b70 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
15b80 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
15b90 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
15ba0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
15bb0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
15bc0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
15bd0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
15be0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
15bf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
15c00 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
15c10 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
15c20 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
15c30 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
15c40 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
15c50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15c60 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
15c70 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
15c80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
15c90 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
15ca0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
15cb0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
15cc0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
15cd0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
15ce0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
15cf0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
15d00 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
15d10 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
15d20 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
15d30 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15d40 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
15d50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
15d60 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
15d70 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
15d80 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
15d90 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
15da0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
15db0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
15dc0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15dd0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
15de0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15df0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
15e00 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
15e10 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
15e20 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
15e30 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
15e40 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
15e50 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15e60 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15e70 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
15e80 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
15e90 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
15ea0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
15eb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
15ec0 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
15ed0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
15ee0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
15ef0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
15f00 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
15f10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15f20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
15f30 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
15f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
15f50 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
15f60 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
15f70 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
15f80 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
15f90 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
15fa0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
15fb0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
15fc0 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
15fd0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
15fe0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
15ff0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
16000 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
16010 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
16020 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
16030 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
16040 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
16050 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
16060 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
16070 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
16080 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
16090 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
160a0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
160b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
160c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
160d0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
160e0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
160f0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
16100 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
16110 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
16120 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
16130 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
16140 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
16150 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
16160 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
16170 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
16180 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
16190 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
161a0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
161b0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
161c0 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
161d0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
161e0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
161f0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
16200 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
16210 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
16220 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
16230 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
16240 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
16250 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
16260 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
16270 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
16280 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
16290 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
162a0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
162b0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
162c0 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
162d0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
162e0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
162f0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
16300 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
16310 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
16320 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
16330 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
16340 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
16350 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
16360 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
16370 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
16380 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
16390 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
163a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
163b0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
163c0 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
163d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
163e0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
163f0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
16400 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
16410 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
16420 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
16430 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
16440 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
16450 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
16460 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
16470 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
16480 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
16490 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
164a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
164b0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
164c0 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
164d0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
164e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
164f0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
16500 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
16510 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
16520 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
16530 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
16540 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
16550 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
16560 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
16570 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
16580 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
16590 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
165a0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
165b0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
165c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
165d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
165e0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
165f0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
16600 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
16610 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
16620 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
16630 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
16640 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
16650 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
16660 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
16670 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
16680 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
16690 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
166a0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
166b0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
166c0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
166d0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
166e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
166f0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
16700 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
16710 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
16720 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
16730 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
16740 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
16750 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
16760 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
16770 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
16780 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
16790 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
167a0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
167b0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
167c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
167d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
167e0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
167f0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
16800 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
16810 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
16820 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
16830 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
16840 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
16850 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16860 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
16870 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
16880 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
16890 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
168a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
168b0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
168c0 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
168d0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
168e0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
168f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
16900 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
16910 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
16920 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
16930 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
16940 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
16950 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
16960 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
16970 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
16980 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
16990 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
169a0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
169b0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
169c0 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
169d0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
169e0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
169f0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
16a00 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
16a10 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
16a20 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
16a30 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
16a40 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
16a50 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
16a60 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
16a70 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
16a80 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
16a90 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
16aa0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
16ab0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
16ac0 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
16ad0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
16ae0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
16af0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16b00 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
16b10 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
16b20 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
16b30 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
16b40 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
16b50 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
16b60 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
16b70 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
16b80 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
16b90 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
16ba0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
16bb0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
16bc0 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
16bd0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
16be0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
16bf0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
16c00 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
16c10 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
16c20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
16c30 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
16c40 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
16c50 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
16c60 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
16c70 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
16c80 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
16c90 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
16ca0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
16cb0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
16cc0 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
16cd0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
16ce0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
16cf0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
16d00 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
16d10 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
16d20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
16d30 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
16d40 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
16d50 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
16d60 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
16d70 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
16d80 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
16d90 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
16da0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
16db0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
16dc0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
16dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
16de0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
16df0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
16e00 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16e10 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
16e20 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
16e30 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
16e40 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
16e50 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
16e60 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
16e70 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
16e80 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
16e90 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
16ea0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
16eb0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
16ec0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
16ed0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
16ee0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
16ef0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
16f00 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
16f10 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
16f20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
16f30 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
16f40 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
16f50 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
16f60 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
16f70 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
16f80 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
16f90 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
16fa0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
16fb0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
16fc0 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
16fd0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
16fe0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
16ff0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
17000 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
17010 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
17020 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
17030 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
17040 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
17050 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
17060 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
17070 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
17080 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
17090 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
170a0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
170b0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
170c0 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
170d0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
170e0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
170f0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
17100 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
17110 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
17120 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
17130 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
17140 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
17150 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
17160 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
17170 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
17180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
17190 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
171a0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
171b0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
171c0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
171d0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
171e0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
171f0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
17200 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
17210 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
17220 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
17230 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
17240 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
17250 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
17260 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
17270 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
17280 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
17290 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
172a0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
172b0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
172c0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
172d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
172e0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
172f0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
17300 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17310 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
17320 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
17330 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
17340 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17350 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17360 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
17370 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
17380 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
17390 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
173a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
173b0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
173c0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
173d0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
173e0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
173f0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
17400 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
17410 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
17420 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
17430 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
17440 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
17450 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
17460 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
17470 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
17480 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
17490 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
174a0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
174b0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
174c0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
174d0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
174e0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
174f0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
17500 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
17510 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
17520 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
17530 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
17540 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
17550 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
17560 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
17570 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
17580 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
17590 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
175a0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
175b0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
175c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
175d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
175e0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
175f0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
17600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17610 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
17620 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
17630 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
17640 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
17650 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
17660 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
17670 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
17680 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
17690 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
176a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
176b0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
176c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
176d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
176e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
176f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
17700 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
17710 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
17720 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
17730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
17740 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
17750 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
17760 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
17770 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
17780 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
17790 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
177a0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
177b0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
177c0 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
177d0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
177e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
177f0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
17800 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
17810 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
17820 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
17830 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
17840 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
17850 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
17860 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
17870 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
17880 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
17890 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
178a0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
178b0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
178c0 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
178d0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
178e0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
178f0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
17900 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
17910 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
17920 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
17930 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
17940 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
17950 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
17960 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
17970 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
17980 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
17990 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
179a0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
179b0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
179c0 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
179d0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
179e0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
179f0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
17a00 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
17a10 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
17a20 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
17a30 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
17a40 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
17a50 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
17a60 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
17a70 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
17a80 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
17a90 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
17aa0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
17ab0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
17ac0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
17ad0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
17ae0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
17af0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
17b00 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
17b10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17b20 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
17b30 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
17b40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
17b50 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
17b60 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
17b70 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
17b80 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
17b90 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
17ba0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
17bb0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
17bc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
17bd0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
17be0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
17bf0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
17c00 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
17c10 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
17c20 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
17c30 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
17c40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17c50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
17c60 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
17c70 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
17c80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
17c90 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
17ca0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
17cb0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
17cc0 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
17cd0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
17ce0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
17cf0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
17d00 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
17d10 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
17d20 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
17d30 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
17d40 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
17d50 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
17d60 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
17d70 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
17d80 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
17d90 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
17da0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
17db0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
17dc0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17dd0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17de0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
17df0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
17e00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17e10 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
17e20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17e30 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
17e40 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
17e50 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
17e60 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
17e70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
17e80 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
17e90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
17ea0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
17eb0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17ec0 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
17ed0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
17ee0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
17ef0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17f00 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
17f10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
17f20 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
17f30 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
17f40 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
17f50 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
17f60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
17f70 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
17f80 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
17f90 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
17fa0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
17fb0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
17fc0 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
17fd0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
17fe0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
17ff0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
18000 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
18010 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
18020 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
18030 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
18040 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
18050 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
18060 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
18070 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
18080 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
18090 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
180a0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
180b0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
180c0 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
180d0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
180e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
180f0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
18100 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
18110 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
18120 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
18130 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
18140 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
18150 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
18160 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
18170 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
18180 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
18190 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
181a0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
181b0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
181c0 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
181d0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
181e0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
181f0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
18200 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
18210 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18220 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
18230 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
18240 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
18250 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
18260 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
18270 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
18280 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
18290 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
182a0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
182b0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
182c0 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
182d0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
182e0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
182f0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
18300 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
18310 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
18320 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
18330 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
18340 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
18350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
18360 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
18370 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
18380 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
18390 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
183a0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
183b0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
183c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
183d0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
183e0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
183f0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
18400 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
18410 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
18420 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
18430 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
18440 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
18450 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
18460 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
18470 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
18480 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
18490 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
184a0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
184b0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
184c0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
184d0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
184e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
184f0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18500 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
18510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18520 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
18530 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
18540 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
18550 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
18560 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
18570 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
18580 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
18590 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
185a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
185b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
185c0 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
185d0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
185e0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
185f0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
18600 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
18610 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
18620 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18630 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
18640 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
18650 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
18660 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
18670 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
18680 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
18690 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
186a0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
186b0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
186c0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
186d0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
186e0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
186f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
18700 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
18710 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
18720 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
18730 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
18740 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
18750 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
18760 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
18770 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
18780 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18790 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
187a0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
187b0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
187c0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
187d0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
187e0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
187f0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
18800 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
18810 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
18820 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
18830 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
18840 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
18850 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
18860 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
18870 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
18880 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
18890 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
188a0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
188b0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
188c0 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
188d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
188e0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
188f0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
18900 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
18910 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
18920 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
18930 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
18940 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
18950 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
18960 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
18970 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
18980 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
18990 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
189a0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
189b0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
189c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
189d0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
189e0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
189f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
18a00 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
18a10 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
18a20 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
18a30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
18a40 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
18a50 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
18a60 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18a70 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18a80 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18a90 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18aa0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18ab0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
18ac0 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
18ad0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18ae0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
18af0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
18b00 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
18b10 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
18b20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
18b30 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
18b40 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
18b50 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
18b60 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18b70 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18b80 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18b90 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18ba0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18bb0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18bc0 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18bd0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18be0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18bf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18c00 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18c10 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18c20 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18c30 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18c40 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18c50 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18c60 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18c70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18c80 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18c90 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18ca0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18cb0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18cc0 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18cd0 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18ce0 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18cf0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18d00 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18d10 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18d20 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18d30 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18d40 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18d50 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18d60 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18d70 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18d80 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18d90 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18da0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18db0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18dc0 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18dd0 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18de0 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18df0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18e00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18e10 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18e20 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18e30 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18e40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18e50 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18e60 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18e70 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18e80 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18e90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18ea0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18eb0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18ec0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18ed0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18ee0 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18ef0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18f00 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18f10 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18f20 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18f30 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18f40 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18f50 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18f60 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18f70 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18f80 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18f90 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18fa0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18fb0 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18fc0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18fd0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18fe0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18ff0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
19000 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
19010 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
19020 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
19030 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
19040 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
19050 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
19060 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
19070 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
19080 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
19090 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
190a0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
190b0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
190c0 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
190d0 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
190e0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
190f0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
19100 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
19110 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
19120 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
19130 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
19140 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
19150 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
19160 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
19170 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
19180 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
19190 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
191a0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
191b0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
191c0 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
191d0 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
191e0 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
191f0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
19200 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
19210 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
19220 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
19230 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
19240 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
19250 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
19260 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
19270 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
19280 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
19290 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
192a0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
192b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
192c0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
192d0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
192e0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
192f0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
19300 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
19310 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
19320 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
19330 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
19340 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19350 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
19360 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
19370 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
19380 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
19390 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
193a0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
193b0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
193c0 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
193d0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
193e0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
193f0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
19400 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
19410 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
19420 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
19430 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
19440 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
19450 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
19460 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
19470 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
19480 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
19490 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  tring.)^.*/.SQLI
194a0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
194b0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
194c0 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53  st char*,...);.S
194d0 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
194e0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
194f0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
19500 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
19510 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
19520 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
19530 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
19540 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
19550 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
19560 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
19570 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
19580 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
19590 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
195a0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
195b0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
195c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
195d0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
195e0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
195f0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
19600 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
19610 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
19620 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
19630 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
19640 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
19650 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
19660 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
19670 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
19680 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
19690 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
196a0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
196b0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
196c0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
196d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
196e0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
196f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
19700 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
19710 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
19720 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
19730 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
19740 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
19750 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
19760 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
19770 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
19780 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
19790 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
197a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
197b0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
197c0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
197d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
197e0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
197f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
19800 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
19810 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
19820 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
19830 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
19840 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
19850 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
19860 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
19870 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
19880 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
19890 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
198a0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
198b0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
198c0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
198d0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
198e0 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
198f0 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
19900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
19910 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
19920 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
19930 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
19940 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
19950 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
19960 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
19970 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
19980 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
19990 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
199a0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
199b0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
199c0 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
199d0 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
199e0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
199f0 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
19a00 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
19a10 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
19a20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
19a30 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
19a40 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
19a50 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
19a60 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
19a70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
19a80 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
19a90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
19aa0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
19ab0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
19ac0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
19ad0 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
19ae0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
19af0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
19b00 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
19b10 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
19b20 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
19b30 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
19b40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
19b50 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
19b60 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
19b70 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
19b80 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
19b90 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
19ba0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19bb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
19bc0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
19bd0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
19be0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
19bf0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
19c00 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
19c10 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
19c20 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19c30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
19c40 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
19c50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19c60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
19c70 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
19c80 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
19c90 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
19ca0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
19cb0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
19cc0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
19cd0 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
19ce0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
19cf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
19d00 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
19d10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19d20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19d30 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
19d40 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
19d50 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
19d60 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
19d70 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
19d80 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
19d90 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
19da0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
19db0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19dc0 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
19dd0 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
19de0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
19df0 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
19e00 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
19e10 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
19e20 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
19e30 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
19e40 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19e50 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
19e60 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
19e70 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
19e80 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
19e90 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
19ea0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
19eb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
19ec0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
19ed0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
19ee0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
19ef0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
19f00 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
19f10 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
19f20 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
19f30 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
19f40 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
19f50 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
19f60 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
19f70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
19f80 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
19f90 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
19fa0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
19fb0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
19fc0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
19fd0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
19fe0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
19ff0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1a000 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1a010 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1a020 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1a030 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1a040 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1a050 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1a060 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1a070 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1a080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1a090 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1a0a0 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73  *.** The Windows
1a0b0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1a0c0 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65  yer calls.** the
1a0d0 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1a0e0 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1a0f0 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1a100 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1a110 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1a120 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1a130 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1a140 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1a150 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1a160 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1a170 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1a180 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1a190 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1a1a0 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64  ion errors are d
1a1b0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
1a1c0 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65  they are reporte
1a1d0 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1a1e0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1a1f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1a200 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1a210 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1a220 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1a230 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1a240 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1a250 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a260 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1a270 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1a280 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1a290 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1a2a0 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1a2b0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1a2c0 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1a2d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1a2e0 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1a2f0 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1a300 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1a310 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1a320 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1a330 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1a340 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1a350 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1a360 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1a370 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1a380 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1a390 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1a3a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1a3b0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1a3c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1a3d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1a3e0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1a3f0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1a400 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1a410 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1a420 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1a430 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1a440 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1a450 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1a460 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1a470 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1a480 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1a490 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1a4a0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1a4b0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1a4c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a4d0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1a4e0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1a4f0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1a500 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1a510 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1a520 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1a530 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1a540 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1a550 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1a560 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1a570 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1a580 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1a590 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1a5a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1a5b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1a5c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1a5d0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1a5e0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1a5f0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a600 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1a610 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1a620 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1a630 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1a640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1a650 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1a660 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1a670 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1a680 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1a690 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1a6a0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1a6b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1a6c0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1a6d0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1a6e0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1a6f0 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1a700 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1a710 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1a720 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1a730 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1a740 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1a750 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1a760 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1a770 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1a780 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1a790 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1a7a0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1a7b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1a7c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1a7d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1a7e0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1a7f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1a800 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1a810 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1a820 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1a830 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1a840 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1a850 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1a860 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1a870 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1a880 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1a890 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1a8a0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1a8b0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1a8c0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1a8d0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1a8e0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1a8f0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1a900 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1a910 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1a920 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1a930 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1a940 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1a950 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1a960 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1a970 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1a980 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1a990 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1a9a0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1a9b0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1a9c0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1a9d0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1a9e0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1a9f0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1aa00 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1aa10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1aa20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1aa30 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1aa40 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1aa50 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1aa60 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1aa70 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1aa80 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1aa90 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1aaa0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1aab0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
1aac0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
1aad0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
1aae0 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
1aaf0 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
1ab00 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
1ab10 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
1ab20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1ab30 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1ab40 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
1ab50 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1ab60 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1ab70 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1ab80 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
1ab90 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
1aba0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
1abb0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1abc0 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1abd0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1abe0 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1abf0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1ac00 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1ac10 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1ac20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1ac30 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1ac40 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1ac50 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1ac60 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1ac70 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1ac80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1ac90 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1aca0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1acb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1acc0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1acd0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1ace0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1acf0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1ad00 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1ad10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ad20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1ad30 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1ad40 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1ad50 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1ad60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ad70 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1ad80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ad90 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ada0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1adb0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1adc0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1add0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1ade0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1adf0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1ae00 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1ae10 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1ae20 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1ae30 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1ae40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1ae50 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ae60 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1ae70 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1ae80 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1ae90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1aea0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1aeb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1aec0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1aed0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1aee0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1aef0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1af00 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1af10 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1af20 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1af30 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1af40 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1af50 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1af60 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1af70 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1af80 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1af90 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1afa0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1afb0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1afc0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1afd0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1afe0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1aff0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1b000 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1b010 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b020 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1b030 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1b040 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1b050 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1b060 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1b070 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1b080 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1b090 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1b0a0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1b0b0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1b0c0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1b0d0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1b0e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1b0f0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1b100 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1b110 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1b120 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1b130 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1b140 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1b150 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1b160 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1b170 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1b180 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1b190 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1b1a0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1b1b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1b1c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1b1d0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1b1e0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1b1f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1b200 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1b210 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1b220 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1b230 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1b240 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1b250 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1b260 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1b270 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1b280 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1b290 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1b2a0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1b2b0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1b2c0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1b2d0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1b2e0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1b2f0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1b300 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1b310 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1b320 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1b330 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1b340 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1b350 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1b360 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1b370 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1b380 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1b390 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b3a0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1b3b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1b3c0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1b3d0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1b3e0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1b3f0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1b400 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1b410 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1b420 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1b430 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1b440 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1b450 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1b460 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1b470 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1b480 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1b490 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1b4a0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1b4b0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1b4c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1b4d0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1b4e0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1b4f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b500 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1b510 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1b520 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1b530 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1b540 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1b550 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1b560 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1b570 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1b580 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1b590 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1b5a0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1b5b0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1b5c0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1b5d0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b5e0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1b5f0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1b600 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1b610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1b620 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1b630 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1b640 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1b650 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1b660 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1b670 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1b680 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1b690 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1b6a0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1b6b0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1b6c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1b6d0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1b6e0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1b6f0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1b700 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1b710 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1b720 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1b730 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1b740 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1b750 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1b760 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1b770 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1b780 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1b790 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1b7a0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1b7b0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1b7c0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1b7d0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1b7e0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1b7f0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1b800 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1b810 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1b820 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1b830 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1b840 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1b850 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1b860 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1b870 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1b880 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1b890 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1b8a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b8b0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1b8c0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1b8d0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1b8e0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1b8f0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1b900 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1b910 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1b920 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1b930 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1b940 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1b950 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1b960 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1b970 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1b980 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1b990 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1b9a0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1b9b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1b9c0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1b9d0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1b9e0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1b9f0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1ba00 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1ba10 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1ba20 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1ba30 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ba40 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ba50 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1ba60 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1ba70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ba80 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1ba90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1baa0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1bab0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1bac0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1bad0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bae0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1baf0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1bb00 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1bb10 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1bb20 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1bb30 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1bb40 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1bb50 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1bb60 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1bb70 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1bb80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1bb90 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1bba0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1bbb0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1bbc0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1bbd0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1bbe0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1bbf0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1bc00 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1bc10 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1bc20 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1bc30 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1bc40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1bc50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1bc60 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1bc70 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1bc80 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1bc90 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1bca0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1bcb0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1bcc0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1bcd0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1bce0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1bcf0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1bd00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1bd10 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1bd20 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1bd30 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1bd40 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1bd50 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1bd60 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1bd70 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1bd80 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1bd90 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1bda0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1bdb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1bdc0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1bdd0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1bde0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1bdf0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1be00 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1be10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1be20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1be30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1be40 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1be50 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1be60 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1be70 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1be80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1be90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1bea0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1beb0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1bec0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1bed0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1bee0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1bef0 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1bf00 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1bf10 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1bf20 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1bf30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1bf40 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1bf50 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1bf60 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1bf70 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1bf80 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1bf90 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1bfa0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1bfb0 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1bfc0 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1bfd0 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1bfe0 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1bff0 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1c000 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1c010 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1c020 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1c030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1c040 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1c050 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1c060 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1c070 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1c080 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1c090 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1c0a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c0b0 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1c0c0 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1c0d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1c0e0 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1c0f0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1c100 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1c110 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1c120 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1c130 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1c140 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1c150 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1c160 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1c170 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1c180 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1c190 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1c1a0 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1c1b0 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1c1c0 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1c1d0 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1c1e0 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1c1f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1c200 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1c210 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1c220 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1c230 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1c240 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1c250 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1c260 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1c270 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1c280 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1c290 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1c2a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c2b0 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1c2c0 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1c2d0 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1c2e0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1c2f0 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1c300 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c310 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1c320 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1c330 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1c340 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1c350 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1c360 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1c370 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1c380 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1c390 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1c3a0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1c3b0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1c3c0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1c3d0 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1c3e0 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1c3f0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1c400 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1c410 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1c420 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1c430 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1c440 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1c450 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1c460 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1c470 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c490 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1c4a0 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1c4b0 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1c4c0 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1c4d0 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1c4e0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1c4f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c500 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c510 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1c520 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1c530 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1c540 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c550 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c560 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1c570 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1c580 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1c590 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c5a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c5b0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1c5c0 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1c5d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1c5e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c5f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c600 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1c610 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1c620 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1c630 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1c650 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1c660 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1c670 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1c680 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c690 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1c6a0 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1c6b0 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1c6c0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1c6d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c6e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c6f0 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1c700 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1c710 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1c720 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c730 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1c740 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1c750 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1c760 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1c770 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1c780 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1c790 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1c7a0 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1c7b0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1c7c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c7d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1c7e0 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1c7f0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c800 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c810 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c820 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1c830 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1c840 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1c850 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1c860 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c870 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1c880 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1c890 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c8a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c8b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c8c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1c8d0 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1c8e0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1c8f0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c900 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c910 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1c920 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1c930 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1c940 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c950 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c960 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1c970 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1c980 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1c990 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c9a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c9b0 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1c9c0 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1c9d0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1c9e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c9f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ca00 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1ca10 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1ca20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1ca30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ca40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ca50 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1ca60 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1ca70 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1ca80 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1ca90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1caa0 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1cab0 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1cac0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1cad0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1cae0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1caf0 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1cb00 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1cb10 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1cb20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1cb30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1cb40 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1cb50 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1cb60 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1cb70 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cb80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1cb90 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1cba0 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1cbb0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1cbc0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1cbd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1cbe0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1cbf0 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1cc00 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1cc10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1cc20 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1cc30 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1cc40 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1cc50 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1cc60 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cc70 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1cc80 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1cc90 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1cca0 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1ccb0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ccc0 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1ccd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1cce0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ccf0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1cd00 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1cd10 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1cd20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1cd30 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1cd40 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1cd50 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1cd60 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1cd70 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1cd80 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1cd90 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1cda0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1cdb0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1cdc0 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1cdd0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1cde0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1cdf0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ce00 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1ce10 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1ce20 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1ce30 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1ce40 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ce50 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1ce60 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1ce70 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1ce80 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1ce90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cea0 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1ceb0 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1cec0 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1ced0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1cee0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1cef0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1cf00 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1cf10 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1cf20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1cf30 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1cf40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1cf50 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1cf60 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1cf70 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1cf80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1cf90 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1cfa0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1cfb0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1cfc0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1cfd0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1cfe0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1cff0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1d000 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1d010 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1d020 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1d030 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d040 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1d050 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1d060 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1d070 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1d080 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1d090 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1d0a0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1d0b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1d0c0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1d0d0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1d0e0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1d0f0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1d100 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1d110 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1d120 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1d130 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1d140 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1d150 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1d160 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1d170 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1d180 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1d190 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1d1a0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1d1b0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1d1c0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1d1d0 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1d1e0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1d1f0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1d200 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1d210 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1d220 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1d230 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1d240 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1d250 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1d260 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1d270 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1d280 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1d290 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1d2a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1d2b0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1d2c0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1d2d0 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1d2e0 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1d2f0 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1d300 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1d310 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1d320 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1d330 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1d340 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1d350 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1d360 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1d370 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1d380 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1d390 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1d3a0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1d3b0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1d3c0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1d3d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1d3e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1d3f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1d400 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1d410 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1d420 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1d430 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1d440 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
1d450 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
1d460 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1d470 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1d480 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1d490 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1d4a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1d4b0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1d4c0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1d4d0 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1d4e0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1d4f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d500 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1d510 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1d520 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1d530 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1d540 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1d550 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1d560 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1d570 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1d580 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1d590 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1d5a0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1d5b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1d5c0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1d5d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1d5e0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1d5f0 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1d600 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1d610 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1d620 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1d630 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1d640 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1d650 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1d660 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1d670 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1d680 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1d690 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1d6a0 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1d6b0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1d6c0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1d6d0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1d6e0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1d6f0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1d700 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1d710 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1d720 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1d730 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1d740 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1d750 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1d760 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1d770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1d780 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1d790 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1d7a0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1d7b0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1d7c0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1d7d0 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1d7e0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1d7f0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1d800 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1d810 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1d820 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1d830 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1d840 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1d850 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1d860 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1d870 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1d880 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1d890 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1d8a0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1d8b0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1d8c0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1d8d0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1d8e0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1d8f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1d900 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1d910 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1d920 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1d930 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1d940 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1d950 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1d960 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1d970 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1d980 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1d990 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1d9a0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1d9b0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1d9c0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1d9d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1d9e0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1d9f0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1da00 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1da10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1da20 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1da30 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1da40 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1da50 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1da60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1da70 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1da80 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1da90 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1daa0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1dab0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1dac0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
1dad0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1dae0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1daf0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1db00 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1db10 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1db20 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1db30 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1db40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1db50 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1db60 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1db70 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1db80 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1db90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1dba0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1dbb0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1dbc0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1dbd0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1dbe0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1dbf0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1dc00 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1dc10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1dc20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1dc30 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1dc40 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1dc50 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1dc60 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1dc70 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1dc80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1dc90 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1dca0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1dcb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1dcc0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1dcd0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1dce0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1dcf0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1dd00 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1dd10 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1dd20 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1dd30 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1dd40 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1dd50 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1dd60 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1dd70 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1dd80 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1dd90 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1dda0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1ddb0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1ddc0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1ddd0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1dde0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1ddf0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1de00 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1de10 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1de20 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1de30 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1de40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1de50 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1de60 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1de70 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1de80 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1de90 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1dea0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1deb0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1dec0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1ded0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1dee0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1def0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1df00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1df10 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1df20 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1df30 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1df40 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1df50 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1df60 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1df70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1df80 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1df90 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1dfa0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1dfb0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1dfc0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1dfd0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1dfe0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1dff0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1e000 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1e010 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1e020 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1e030 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1e040 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1e050 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1e060 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1e070 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1e080 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1e090 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1e0a0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1e0b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1e0c0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1e0d0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1e0e0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
1e0f0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1e100 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
1e110 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1e120 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1e130 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1e140 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1e150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e160 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1e170 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1e180 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1e190 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1e1a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1e1b0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1e1c0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1e1d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1e1e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e1f0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1e200 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1e210 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1e220 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1e230 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1e240 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1e250 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1e260 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1e270 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1e280 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1e290 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1e2a0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1e2b0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1e2c0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1e2d0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1e2e0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1e2f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e300 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1e310 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1e320 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1e330 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e340 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1e350 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1e360 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1e370 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1e380 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1e390 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1e3a0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1e3b0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1e3c0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1e3d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1e3e0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1e3f0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1e400 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e410 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1e420 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1e430 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1e440 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
1e450 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1e460 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
1e470 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1e480 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
1e490 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
1e4a0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1e4b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1e4c0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1e4d0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1e4e0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1e4f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e500 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1e510 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1e520 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1e530 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1e540 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1e550 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1e560 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1e570 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1e580 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1e590 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1e5a0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1e5b0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1e5c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1e5d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1e5e0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1e5f0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1e600 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1e610 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1e620 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1e630 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1e640 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1e650 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1e660 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1e670 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1e680 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1e690 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1e6a0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1e6b0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1e6c0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1e6d0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1e6e0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1e6f0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1e700 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1e710 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1e720 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1e730 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1e740 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1e750 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1e760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e770 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1e780 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1e790 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1e7a0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1e7b0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
1e7c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1e7d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1e7e0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1e7f0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1e800 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1e810 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1e820 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1e830 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1e840 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1e850 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e860 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1e870 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1e880 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1e890 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1e8a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1e8b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1e8c0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1e8d0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1e8e0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1e8f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1e900 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1e910 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1e920 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1e930 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1e940 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1e950 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1e960 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1e970 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1e980 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1e990 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1e9a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1e9b0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1e9c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1e9d0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1e9e0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1e9f0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1ea00 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1ea10 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1ea20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1ea30 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1ea40 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1ea50 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1ea60 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1ea70 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1ea80 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1ea90 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1eaa0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1eab0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1eac0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1ead0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1eae0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1eaf0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1eb00 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1eb10 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1eb20 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1eb30 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1eb40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1eb50 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1eb60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1eb70 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1eb80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
1eb90 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
1eba0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
1ebb0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
1ebc0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
1ebd0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
1ebe0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1ebf0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
1ec00 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1ec10 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
1ec20 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
1ec30 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1ec40 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1ec50 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
1ec60 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1ec70 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1ec80 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1ec90 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
1eca0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
1ecb0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1ecc0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1ecd0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
1ece0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
1ecf0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
1ed00 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
1ed10 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
1ed20 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
1ed30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
1ed40 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
1ed50 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
1ed60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1ed70 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
1ed80 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1ed90 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
1eda0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1edb0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
1edc0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
1edd0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
1ede0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
1edf0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
1ee00 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
1ee10 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
1ee20 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
1ee30 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
1ee40 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1ee50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1ee60 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
1ee70 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
1ee80 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
1ee90 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
1eea0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
1eeb0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
1eec0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
1eed0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
1eee0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
1eef0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
1ef00 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
1ef10 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
1ef20 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
1ef30 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
1ef40 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
1ef50 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
1ef60 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
1ef70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
1ef80 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
1ef90 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
1efa0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
1efb0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
1efc0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
1efd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1efe0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
1eff0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
1f000 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
1f010 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
1f020 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
1f030 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
1f040 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1f050 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
1f060 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
1f070 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
1f080 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
1f090 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
1f0a0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
1f0b0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
1f0c0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
1f0d0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
1f0e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1f0f0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
1f100 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
1f110 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
1f120 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
1f130 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
1f140 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
1f150 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
1f160 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
1f170 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
1f180 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
1f190 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
1f1a0 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
1f1b0 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
1f1c0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
1f1d0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
1f1e0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
1f1f0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
1f200 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
1f210 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
1f220 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
1f230 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1f240 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
1f250 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
1f260 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
1f270 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
1f280 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1f290 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
1f2a0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
1f2b0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
1f2c0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
1f2d0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1f2e0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1f2f0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
1f300 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
1f310 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1f320 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
1f330 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
1f340 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
1f350 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1f360 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
1f370 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
1f380 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
1f390 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
1f3a0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
1f3b0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1f3c0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1f3d0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
1f3e0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
1f3f0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
1f400 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1f410 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
1f420 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
1f430 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
1f440 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
1f450 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1f460 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f470 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
1f480 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
1f490 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
1f4a0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
1f4b0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
1f4c0 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77  w" or.**     "rw
1f4d0 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  c". Attempting t
1f4e0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
1f4f0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 20 61  other value is a
1f500 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
1f510 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
1f520 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
1f530 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1f540 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
1f550 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
1f560 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
1f570 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1f580 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
1f590 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
1f5a0 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
1f5b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1f5c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f5d0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1f5e0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1f5f0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1f600 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1f610 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1f620 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1f630 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1f640 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1f650 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1f660 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1f670 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1f680 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1f690 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
1f6a0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
1f6b0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1f6c0 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
1f6d0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1f6e0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
1f6f0 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73  EN_CREATE. ^If s
1f700 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f710 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64   is .**     used
1f720 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  , it is an error
1f730 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
1f740 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65  lue for the mode
1f750 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
1f760 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20  is .**     less 
1f770 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
1f780 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
1f790 62 79 20 74 68 65 20 66 6c 61 67 73 20 70 61 73  by the flags pas
1f7a0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1f7b0 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74   .**     paramet
1f7c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  er..**.**   <li>
1f7d0 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
1f7e0 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
1f7f0 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1f800 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
1f810 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
1f820 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
1f830 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
1f840 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1f850 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
1f860 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
1f870 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
1f880 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
1f890 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
1f8a0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
1f8b0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
1f8c0 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
1f8d0 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
1f8e0 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
1f8f0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1f900 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
1f910 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1f920 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
1f930 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f940 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1f950 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
1f960 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
1f970 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
1f980 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
1f990 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
1f9a0 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 75  y behaviour requ
1f9b0 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
1f9c0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1f9d0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1f9e0 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
1f9f0 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
1fa00 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ul>.**.**
1fa10 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
1fa20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
1fa30 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
1fa40 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
1fa50 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
1fa60 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65  rror.  Future ve
1fa70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fa80 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e   might understan
1fa90 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65  d additional que
1faa0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ry.** parameters
1fab0 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70  .  See "[query p
1fac0 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73  arameters with s
1fad0 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74  pecial meaning t
1fae0 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a  o SQLite]" for.*
1faf0 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
1fb00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
1fb10 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  [[URI filename e
1fb20 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52  xamples]] <h3>UR
1fb30 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
1fb40 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c  les</h3>.**.** <
1fb50 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
1fb60 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65   align=center ce
1fb70 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20  llpadding=5>.** 
1fb80 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c  <tr><th> URI fil
1fb90 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75  enames <th> Resu
1fba0 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  lts.** <tr><td> 
1fbb0 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64  file:data.db <td
1fbc0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
1fbd0 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1fbe0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
1fbf0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e  rrent directory.
1fc00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1fc10 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
1fc20 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20  a.db<br>.**     
1fc30 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d       file:///hom
1fc40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
1fc50 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  br> .**         
1fc60 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73   file://localhos
1fc70 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  t/home/fred/data
1fc80 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a  .db <br> <td> .*
1fc90 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1fca0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1fcb0 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  e "/home/fred/da
1fcc0 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c  ta.db"..** <tr><
1fcd0 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73  td> file://darks
1fce0 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  tar/home/fred/da
1fcf0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1fd00 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
1fd10 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20  . "darkstar" is 
1fd20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64  not a recognized
1fd30 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c   authority..** <
1fd40 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68  tr><td style="wh
1fd50 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70  ite-space:nowrap
1fd60 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  "> .**          
1fd70 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d  file:///C:/Docum
1fd80 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74  ents%20and%20Set
1fd90 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74  tings/fred/Deskt
1fda0 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20  op/data.db.**   
1fdb0 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f    <td> Windows o
1fdc0 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69  nly: Open the fi
1fdd0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20  le "data.db" on 
1fde0 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f  fred's desktop o
1fdf0 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20  n drive.**      
1fe00 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61      C:. Note tha
1fe10 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69  t the %20 escapi
1fe20 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70  ng in this examp
1fe30 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74  le is not strict
1fe40 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ly .**          
1fe50 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63  necessary - spac
1fe60 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e  e characters can
1fe70 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c   be used literal
1fe80 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69  ly.**          i
1fe90 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e  n URI filenames.
1fea0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1feb0 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
1fec0 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20  o&cache=private 
1fed0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1fee0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74    Open file "dat
1fef0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
1ff00 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66  rent directory f
1ff10 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63  or read-only acc
1ff20 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20  ess..**         
1ff30 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   Regardless of w
1ff40 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68  hether or not sh
1ff50 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20  ared-cache mode 
1ff60 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a  is enabled by.**
1ff70 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c            defaul
1ff80 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65  t, use a private
1ff90 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c   cache..** <tr><
1ffa0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
1ffb0 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d  red/data.db?vfs=
1ffc0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e  unix-nolock <td>
1ffd0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1ffe0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
1fff0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
20000 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
20010 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a   "unix-nolock"..
20020 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
20030 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
20040 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
20050 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
20060 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
20070 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
20080 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
20090 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
200a0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
200b0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
200c0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
200d0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
200e0 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
200f0 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
20100 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
20110 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
20120 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
20130 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
20140 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
20150 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
20160 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
20170 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
20180 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
20190 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
201a0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
201b0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
201c0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
201d0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
201e0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
201f0 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
20200 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
20210 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
20220 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
20230 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
20240 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
20250 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
20260 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
20270 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
20280 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
20290 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
202a0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
202b0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
202c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
202d0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
202e0 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
202f0 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
20300 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
20310 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
20320 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
20330 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
20340 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
20350 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
20360 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
20370 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
20380 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
20390 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
203a0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
203b0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
203c0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
203d0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
203e0 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
203f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
20400 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20410 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  2()..*/.SQLITE_A
20420 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
20430 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
20440 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
20450 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
20460 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
20470 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
20480 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
20490 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
204a0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
204b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
204c0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
204d0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
204e0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
204f0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
20500 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
20510 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
20520 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
20530 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
20540 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
20550 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
20560 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
20570 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
20580 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
20590 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
205a0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
205b0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
205c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
205d0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
205e0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
205f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
20600 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
20610 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
20620 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
20630 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
20640 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
20650 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
20660 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
20670 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
20680 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
20690 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
206a0 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
206b0 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
206c0 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
206d0 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
206e0 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
206f0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
20700 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
20710 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
20720 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
20730 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
20740 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
20750 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
20760 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
20770 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
20780 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
20790 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
207a0 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
207b0 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
207c0 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
207d0 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
207e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
207f0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
20800 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
20810 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
20820 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
20830 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
20840 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
20850 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
20860 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
20870 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
20880 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
20890 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
208a0 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
208b0 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
208c0 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
208d0 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
208e0 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
208f0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
20900 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
20910 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
20920 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20930 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
20940 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
20950 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
20960 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
20970 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
20980 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
20990 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
209a0 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
209b0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
209c0 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
209d0 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
209e0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
209f0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
20a00 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
20a10 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
20a20 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
20a30 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
20a40 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
20a50 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
20a60 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
20a70 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
20a80 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
20a90 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
20aa0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
20ab0 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
20ac0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20ad0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
20ae0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
20af0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
20b00 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
20b10 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
20b20 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
20b30 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
20b40 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
20b50 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
20b60 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
20b70 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
20b80 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
20b90 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
20ba0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
20bb0 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
20bc0 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
20bd0 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
20be0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
20bf0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
20c00 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
20c10 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
20c20 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
20c30 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
20c40 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
20c50 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
20c60 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
20c70 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
20c80 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
20c90 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
20ca0 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
20cb0 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
20cc0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
20cd0 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
20ce0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
20cf0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
20d00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20d10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
20d20 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
20d30 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
20d40 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
20d50 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
20d60 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
20d70 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
20d80 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
20d90 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
20da0 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
20db0 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
20dc0 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
20dd0 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
20de0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
20df0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
20e00 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
20e10 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
20e20 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
20e30 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
20e40 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
20e50 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
20e60 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
20e70 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
20e80 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
20e90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
20ea0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20eb0 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
20ec0 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
20ed0 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
20ee0 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
20ef0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
20f00 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
20f10 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
20f20 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
20f30 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
20f40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20f50 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
20f60 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e  Messages.**.** ^
20f70 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  The sqlite3_errc
20f80 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ode() interface 
20f90 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65  returns the nume
20fa0 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  ric [result code
20fb0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
20fc0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
20fd0 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  or the most rece
20fe0 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65  nt failed sqlite
20ff0 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20  3_* API call.** 
21000 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
21010 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
21020 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72  ection]. If a pr
21030 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69  ior API call fai
21040 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d  led.** but the m
21050 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
21060 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74  all succeeded, t
21070 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
21080 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
21090 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
210a0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71  efined.  ^The sq
210b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
210c0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
210d0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
210e0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
210f0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
21100 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
21110 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
21120 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
21130 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
21140 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
21150 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21160 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
21170 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
21180 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
21190 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
211a0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
211b0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
211c0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
211d0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
211e0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
211f0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
21200 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
21210 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
21220 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
21230 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
21240 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
21250 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
21260 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
21270 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
21280 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
21290 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
212a0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
212b0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
212c0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
212d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
212e0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
212f0 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
21300 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
21310 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
21320 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
21330 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
21340 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
21350 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
21360 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
21370 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
21380 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
21390 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
213a0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
213b0 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
213c0 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
213d0 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
213e0 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
213f0 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
21400 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
21410 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
21420 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
21430 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
21440 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
21450 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
21460 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
21470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21480 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
21490 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
214a0 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
214b0 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
214c0 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
214d0 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
214e0 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
214f0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
21500 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
21510 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
21520 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
21530 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
21540 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
21550 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
21560 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
21570 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
21580 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
21590 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
215a0 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
215b0 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
215c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
215d0 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
215e0 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
215f0 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
21600 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
21610 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
21620 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  I int sqlite3_er
21630 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
21640 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
21650 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
21660 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
21670 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
21680 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
21690 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
216a0 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
216b0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
216c0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
216d0 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
216e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
216f0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
21700 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
21710 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
21720 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
21730 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
21740 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
21750 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
21760 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
21770 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
21780 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
21790 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
217a0 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
217b0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
217c0 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
217d0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
217e0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
217f0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
21800 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
21810 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
21820 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
21830 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
21840 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
21850 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
21860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
21870 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
21880 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
21890 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
218a0 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
218b0 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
218c0 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
218d0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
218e0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
218f0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
21900 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
21910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21920 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
21930 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
21940 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
21950 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
21960 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
21970 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
21980 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
21990 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
219a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
219b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
219c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
219d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
219e0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
219f0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
21a00 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
21a10 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
21a20 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
21a30 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
21a40 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
21a50 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
21a60 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
21a70 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
21a80 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
21a90 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
21aa0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
21ab0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
21ac0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
21ad0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
21ae0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
21af0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
21b00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
21b10 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
21b20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21b30 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
21b40 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
21b50 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
21b60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21b70 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
21b80 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
21b90 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
21ba0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
21bb0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
21bc0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
21bd0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
21be0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
21bf0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
21c00 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
21c10 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
21c20 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
21c30 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
21c40 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
21c50 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
21c60 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
21c70 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
21c80 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
21c90 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
21ca0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
21cb0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
21cc0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
21cd0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
21ce0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
21cf0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
21d00 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
21d10 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
21d20 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
21d30 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
21d40 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
21d50 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
21d60 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
21d70 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
21d80 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
21d90 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
21da0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
21db0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
21dc0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
21dd0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
21de0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
21df0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
21e00 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
21e10 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
21e20 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
21e30 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
21e40 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
21e50 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
21e60 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
21e70 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
21e80 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
21e90 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
21ea0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
21eb0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
21ec0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
21ed0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
21ee0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
21ef0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
21f00 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
21f10 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
21f20 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
21f30 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
21f40 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
21f50 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
21f60 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
21f70 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
21f80 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
21f90 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
21fa0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
21fb0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
21fc0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
21fd0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
21fe0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
21ff0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
22000 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
22010 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
22020 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
22030 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
22040 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
22050 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
22060 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
22070 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
22080 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
22090 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
220a0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
220b0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
220c0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
220d0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
220e0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
220f0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
22100 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
22110 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
22120 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
22130 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
22140 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
22150 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
22160 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
22170 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
22180 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
22190 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
221a0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
221b0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
221c0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
221d0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
221e0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
221f0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
22200 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
22210 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
22220 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
22230 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
22240 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
22250 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
22260 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
22270 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
22280 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
22290 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
222a0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
222b0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
222c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
222d0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
222e0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
222f0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
22300 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
22310 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
22320 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
22330 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
22340 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
22350 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
22360 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
22370 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
22380 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22390 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
223a0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
223b0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
223c0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
223d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
223e0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
223f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
22400 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
22410 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
22420 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
22430 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
22440 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
22450 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22460 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22470 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22480 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22490 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
224a0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
224b0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
224c0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
224d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
224e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
224f0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
22500 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
22510 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22520 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
22530 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
22540 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
22550 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
22560 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
22570 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
22580 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
22590 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
225a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
225b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
225c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
225d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
225e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
225f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22600 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
22610 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22620 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
22630 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
22640 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
22650 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
22660 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
22670 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
22680 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
22690 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
226a0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
226b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
226c0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
226d0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
226e0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
226f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
22700 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
22710 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
22720 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
22730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22740 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
22750 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
22760 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
22770 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
22780 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
22790 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
227a0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
227b0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
227c0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
227d0 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
227e0 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
227f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
22800 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
22810 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
22820 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
22830 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
22840 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
22850 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
22860 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22870 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
22880 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
22890 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
228a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
228b0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
228c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
228d0 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
228e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
228f0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
22900 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
22910 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
22920 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
22930 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
22940 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
22950 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
22960 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
22970 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22980 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
22990 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
229a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
229b0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
229c0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
229d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
229e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
229f0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
22a00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
22a10 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
22a20 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
22a30 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
22a40 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
22a50 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
22a60 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
22a70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22a80 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
22a90 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
22aa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
22ab0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
22ac0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22ad0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
22ae0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
22af0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
22b00 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
22b10 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
22b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22b30 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
22b40 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
22b50 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
22b60 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
22b70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
22b80 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
22b90 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
22ba0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
22bb0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
22bc0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
22bd0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
22be0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
22bf0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
22c00 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
22c10 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
22c20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
22c30 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22c40 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
22c50 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
22c60 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22c70 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
22c80 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
22c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22ca0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22cb0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
22cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22cd0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22ce0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
22cf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22d00 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
22d10 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
22d20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22d30 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
22d40 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
22d50 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
22d60 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
22d70 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
22d80 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
22d90 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
22da0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
22db0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
22dc0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
22dd0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22de0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
22df0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
22e00 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
22e10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
22e20 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
22e30 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
22e40 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
22e50 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
22e60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
22e70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
22e80 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
22e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22ea0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
22eb0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
22ec0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
22ed0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
22ee0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
22ef0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
22f00 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
22f10 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
22f20 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
22f30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
22f40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
22f50 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
22f60 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
22f70 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
22f80 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
22f90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22fa0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
22fb0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
22fc0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
22fd0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
22fe0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
22ff0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
23000 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
23010 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
23020 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
23030 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
23040 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
23050 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
23060 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
23070 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
23080 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
23090 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
230a0 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
230b0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
230c0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
230d0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
230e0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
230f0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
23100 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
23110 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
23120 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
23130 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
23140 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
23150 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
23160 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
23170 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
23180 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
23190 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
231a0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
231b0 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
231c0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
231d0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
231e0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
231f0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
23200 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
23210 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
23220 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
23230 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
23240 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
23250 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
23260 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
23270 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
23280 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
23290 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
232a0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
232b0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
232c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
232d0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
232e0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
232f0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
23300 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
23310 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
23320 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
23330 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
23340 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
23350 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
23360 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
23370 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
23380 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23390 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
233a0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
233b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
233c0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
233d0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
233e0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
233f0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
23400 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
23410 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
23420 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
23430 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
23440 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
23450 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
23460 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
23470 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
23480 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
23490 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
234a0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
234b0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
234c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
234d0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
234e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
234f0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
23500 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
23510 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
23520 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
23530 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
23540 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
23550 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
23560 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
23570 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23580 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
23590 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
235a0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
235b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
235c0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
235d0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
235e0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
235f0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
23600 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
23610 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
23620 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
23630 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
23640 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
23650 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
23660 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
23670 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
23680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
23690 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
236a0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
236b0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
236c0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
236d0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
236e0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
236f0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
23700 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
23710 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
23720 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
23730 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
23740 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
23750 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
23760 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
23770 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
23780 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
23790 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
237a0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
237b0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
237c0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
237d0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
237e0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
237f0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
23800 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
23810 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
23820 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
23830 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
23840 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23850 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
23860 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
23870 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
23880 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
23890 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
238a0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
238b0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
238c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
238d0 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
238e0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
238f0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
23900 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
23910 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
23920 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
23930 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
23940 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
23950 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
23960 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
23970 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
23980 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
23990 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
239a0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
239b0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
239c0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
239d0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
239e0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
239f0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
23a00 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
23a10 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
23a20 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
23a30 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
23a40 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
23a50 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
23a60 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
23a70 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
23a80 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
23a90 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
23aa0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
23ab0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
23ac0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
23ad0 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
23ae0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
23af0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
23b00 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
23b10 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
23b20 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
23b30 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
23b40 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
23b50 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
23b60 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
23b70 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
23b80 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
23b90 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
23ba0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
23bb0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
23bc0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
23bd0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
23be0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
23bf0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
23c00 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
23c10 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
23c20 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
23c30 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
23c40 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
23c50 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
23c60 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
23c70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23c80 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
23c90 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
23ca0 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
23cb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
23cc0 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
23cd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
23ce0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
23cf0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23d00 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
23d10 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
23d20 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
23d30 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
23d40 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
23d50 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
23d60 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
23d70 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
23d80 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
23d90 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
23da0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
23db0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
23dc0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
23dd0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
23de0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
23df0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
23e00 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
23e10 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
23e20 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
23e30 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
23e40 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
23e50 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
23e60 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
23e70 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
23e80 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
23e90 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
23ea0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
23eb0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
23ec0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
23ed0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
23ee0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
23ef0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
23f00 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
23f10 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
23f20 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
23f30 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
23f40 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
23f50 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
23f60 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
23f70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
23f80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
23f90 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
23fa0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
23fb0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
23fc0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
23fd0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
23fe0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
23ff0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
24000 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
24010 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
24020 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
24030 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
24040 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
24050 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
24060 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
24070 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
24080 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
24090 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
240a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
240b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
240c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
240d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
240e0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
240f0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
24100 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
24110 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
24120 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
24130 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
24140 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
24150 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
24160 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
24170 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
24180 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
24190 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
241a0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
241b0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
241c0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
241d0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
241e0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
241f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24200 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
24210 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
24220 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
24230 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
24240 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
24250 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
24260 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
24270 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
24280 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24290 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
242a0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
242b0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
242c0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
242d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
242e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
242f0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
24300 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
24310 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
24320 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
24330 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
24340 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
24350 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
24360 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
24370 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
24380 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
24390 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
243a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
243b0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
243c0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
243d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
243e0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
243f0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
24400 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
24410 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
24420 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
24430 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
24440 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
24450 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
24460 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
24470 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
24480 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
24490 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
244a0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
244b0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
244c0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
244d0 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
244e0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
244f0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
24500 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
24510 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
24520 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
24530 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
24540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24550 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
24560 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
24570 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
24580 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
24590 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
245a0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
245b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
245c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
245d0 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
245e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
245f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
24600 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
24610 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
24620 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
24630 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
24640 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
24650 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
24660 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
24670 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
24680 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
24690 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
246a0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
246b0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
246c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
246d0 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
246e0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
246f0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
24700 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
24710 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
24720 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
24730 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
24740 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
24750 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
24760 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
24770 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
24780 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
24790 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
247a0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
247b0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
247c0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
247d0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
247e0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
247f0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
24800 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
24810 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
24820 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
24830 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
24840 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
24850 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
24860 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
24870 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
24880 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
24890 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
248a0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
248b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
248c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
248d0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
248e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
248f0 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73  ent Has Been Res
24900 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
24910 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
24920 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
24930 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
24940 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
24950 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24960 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
24970 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
24980 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
24990 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
249a0 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e   but has not run
249b0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
249c0 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a  nd/or has not .*
249d0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
249e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
249f0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
24a00 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
24a10 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
24a20 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
24a30 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
24a40 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
24a50 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
24a60 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
24a70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
24a80 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
24a90 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
24aa0 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
24ab0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24ac0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
24ad0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
24ae0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
24af0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
24b00 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
24b10 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
24b20 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
24b30 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
24b40 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
24b50 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
24b60 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
24b70 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
24b80 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
24b90 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
24ba0 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
24bb0 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
24bc0 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
24bd0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
24be0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
24bf0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
24c00 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
24c10 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
24c20 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
24c30 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c  e3_stmt_busy(sql
24c40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
24c50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
24c60 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
24c70 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
24c80 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
24c90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24ca0 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
24cb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
24cc0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
24cd0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
24ce0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
24cf0 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
24d00 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
24d10 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
24d20 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
24d30 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
24d40 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
24d50 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
24d60 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
24d70 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
24d80 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
24d90 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
24da0 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
24db0 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
24dc0 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
24dd0 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
24de0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24df0 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
24e00 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
24e10 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
24e20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
24e30 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
24e40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24e50 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
24e60 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
24e70 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
24e80 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
24e90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
24ea0 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
24eb0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
24ec0 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
24ed0 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
24ee0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
24ef0 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
24f00 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
24f10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24f20 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
24f30 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
24f40 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
24f50 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
24f60 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
24f70 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
24f80 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
24f90 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
24fa0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
24fb0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
24fc0 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
24fd0 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
24fe0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
24ff0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
25000 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
25010 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
25020 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
25030 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
25040 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
25050 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
25060 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
25070 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
25080 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
25090 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
250a0 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
250b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
250c0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
250d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
250e0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
250f0 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
25100 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
25110 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
25120 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
25130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
25140 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
25150 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
25160 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
25170 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
25180 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
25190 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
251a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
251b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
251c0 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
251d0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
251e0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
251f0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
25200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
25210 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
25220 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
25230 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
25240 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
25250 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
25260 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
25270 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
25280 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
25290 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
252a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
252b0 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
252c0 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
252d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
252e0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
252f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
25300 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
25310 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
25320 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
25330 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
25340 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
25350 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
25360 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
25370 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25380 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
25390 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
253a0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
253b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
253c0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
253d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
253e0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
253f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25400 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
25410 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
25420 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
25430 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
25440 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
25450 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
25460 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
25470 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
25480 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
25490 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
254a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
254b0 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
254c0 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
254d0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
254e0 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
254f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
25500 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25510 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
25520 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
25530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25540 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
25550 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
25560 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
25570 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
25580 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
25590 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
255a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
255b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
255c0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
255d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
255e0 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
255f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
25600 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
25610 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
25620 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
25630 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25640 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
25650 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25660 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
25670 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
25680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
25690 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
256a0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
256b0 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
256c0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
256d0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
256e0 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
256f0 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
25700 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
25710 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
25720 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
25730 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
25740 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
25750 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
25760 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
25770 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
25780 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
25790 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
257a0 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
257b0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
257c0 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
257d0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
257e0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
257f0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
25800 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
25810 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
25820 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
25830 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
25840 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
25850 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
25860 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
25870 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
25880 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
25890 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
258a0 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
258b0 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
258c0 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
258d0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
258e0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
258f0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
25900 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
25910 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
25920 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
25930 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
25940 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
25950 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
25960 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
25970 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25980 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
25990 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
259a0 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
259b0 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
259c0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
259d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
259e0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
259f0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
25a00 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
25a10 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
25a20 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
25a30 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
25a40 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
25a50 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
25a60 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
25a70 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
25a80 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
25a90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
25aa0 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
25ab0 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
25ac0 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
25ad0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
25ae0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
25af0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
25b00 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
25b10 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
25b20 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
25b30 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
25b40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
25b50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
25b60 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
25b70 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
25b80 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
25b90 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
25ba0 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
25bb0 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
25bc0 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
25bd0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
25be0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
25bf0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
25c00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25c10 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
25c20 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
25c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
25c40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
25c50 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
25c60 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
25c70 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
25c80 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
25c90 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
25ca0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
25cb0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
25cc0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
25cd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
25ce0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
25cf0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
25d00 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
25d10 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
25d20 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
25d30 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
25d40 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
25d50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25d60 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
25d70 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
25d80 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
25d90 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25da0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
25db0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
25dc0 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  r..** If a non-n
25dd0 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
25de0 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
25df0 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
25e00 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
25e10 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
25e20 65 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61  ext16() then tha
25e30 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
25e40 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
25e50 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
25e60 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
25e70 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
25e80 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
25e90 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
25ea0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
25eb0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
25ec0 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
25ed0 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
25ee0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
25ef0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25f00 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
25f10 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
25f20 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
25f30 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
25f40 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
25f50 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
25f60 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
25f70 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
25f80 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
25f90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
25fa0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
25fb0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
25fc0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62  lob(), sqlite3_b
25fd0 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a  ind_text(), and.
25fe0 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
25ff0 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65  text16() is a de
26000 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
26010 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
26020 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
26030 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
26040 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
26050 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
26060 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
26070 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
26080 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
26090 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
260a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
260b0 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20  bind_blob(),.** 
260c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
260d0 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  t(), or sqlite3_
260e0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61  bind_text16() fa
260f0 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68  ils.  .** ^If th
26100 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
26110 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
26120 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
26130 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
26140 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
26150 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
26160 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
26170 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
26180 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
26190 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
261a0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
261b0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
261c0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
261d0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
261e0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
261f0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
26200 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
26210 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
26220 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
26230 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
26240 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
26250 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
26260 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
26270 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
26280 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
26290 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
262a0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
262b0 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
262c0 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
262d0 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
262e0 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
262f0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
26300 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
26310 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
26320 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
26330 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
26340 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
26350 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
26360 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
26370 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
26380 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
26390 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
263a0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
263b0 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
263c0 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
263d0 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
263e0 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
263f0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
26400 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
26410 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
26420 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
26430 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
26440 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
26450 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
26460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26470 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
26480 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26490 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
264a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
264b0 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
264c0 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
264d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
264e0 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
264f0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
26500 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
26510 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
26520 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
26530 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
26540 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26550 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
26560 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
26570 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
26580 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
26590 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
265a0 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
265b0 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
265c0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
265d0 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
265e0 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
265f0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
26600 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
26610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
26620 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
26630 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
26640 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
26650 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
26660 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
26670 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
26680 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
26690 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
266a0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
266b0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
266c0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
266d0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
266e0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
266f0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
26700 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
26710 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
26720 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
26730 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
26740 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
26750 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
26760 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
26770 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
26780 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26790 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
267a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
267b0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
267c0 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
267d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
267e0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
267f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
26800 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
26810 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
26820 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26830 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
26840 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
26850 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26860 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
26870 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26880 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
26890 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
268a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
268b0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
268c0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
268d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
268e0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
268f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
26900 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
26910 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
26920 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
26930 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26940 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
26950 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
26960 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
26970 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
26980 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26990 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
269a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
269b0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
269c0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
269d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
269e0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
269f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
26a00 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
26a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26a20 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
26a30 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
26a40 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
26a50 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
26a60 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
26a70 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
26a80 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
26a90 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
26aa0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
26ab0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
26ac0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
26ad0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
26ae0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
26af0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
26b00 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
26b10 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
26b20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26b30 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
26b40 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
26b50 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
26b60 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
26b70 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
26b80 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
26b90 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
26ba0 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
26bb0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
26bc0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
26bd0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
26be0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
26bf0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
26c00 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
26c10 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
26c20 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
26c30 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
26c40 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
26c50 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
26c60 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26c70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26c80 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
26c90 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
26ca0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
26cb0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
26cc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26cd0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
26ce0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
26cf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
26d00 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
26d10 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
26d20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
26d30 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
26d40 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
26d50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
26d60 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
26d70 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
26d80 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
26d90 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
26da0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
26db0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
26dc0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
26dd0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
26de0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
26df0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
26e00 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
26e10 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
26e20 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
26e30 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
26e40 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
26e50 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
26e60 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
26e70 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
26e80 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
26e90 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
26ea0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
26eb0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
26ec0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
26ed0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
26ee0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
26ef0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
26f00 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
26f10 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
26f20 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
26f30 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
26f40 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
26f50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
26f60 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
26f70 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
26f80 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
26f90 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
26fa0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
26fb0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
26fc0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
26fd0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
26fe0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
26ff0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
27000 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
27010 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
27020 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
27030 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
27040 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
27050 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
27060 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
27070 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
27080 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27090 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
270a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
270b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
270c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
270d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
270e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
270f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
27100 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27110 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
27120 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
27130 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
27140 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
27150 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
27160 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
27170 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
27180 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
27190 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
271a0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
271b0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
271c0 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
271d0 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
271e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
271f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
27200 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
27210 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
27220 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
27230 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
27240 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
27250 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
27260 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
27270 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
27280 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
27290 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
272a0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
272b0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
272c0 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
272d0 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
272e0 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
272f0 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
27300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
27310 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
27320 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27330 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
27340 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
27350 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
27360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
27370 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
27380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27390 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
273a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
273b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
273c0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
273d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
273e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
273f0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
27400 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
27410 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
27420 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
27430 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
27440 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
27450 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
27460 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
27470 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
27480 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27490 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
274a0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
274b0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
274c0 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
274d0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
274e0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
274f0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
27500 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27510 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
27520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
27530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27540 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
27550 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
27560 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
27570 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
27580 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
27590 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
275a0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
275b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
275c0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
275d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
275e0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
275f0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
27600 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
27610 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
27620 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
27630 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27640 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
27650 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nt()].*/.SQLITE_
27660 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27670 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
27680 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27690 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
276a0 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
276b0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
276c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
276d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
276e0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
276f0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
27700 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
27710 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
27720 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27730 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
27740 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
27750 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
27760 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
27770 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
27780 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
27790 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
277a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
277b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
277c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
277d0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
277e0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
277f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
27800 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
27810 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
27820 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
27830 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
27840 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
27850 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
27860 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
27870 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
27880 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
27890 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
278a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
278b0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
278c0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
278d0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
278e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
278f0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
27900 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27910 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
27920 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
27930 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
27940 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
27950 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
27960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
27970 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
27980 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
27990 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
279a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
279b0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
279c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
279d0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
279e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
279f0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
27a00 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
27a10 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
27a20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
27a30 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
27a40 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
27a50 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
27a60 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
27a70 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
27a80 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
27a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
27aa0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
27ab0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
27ac0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
27ad0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
27ae0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
27af0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
27b00 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
27b10 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
27b20 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
27b30 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
27b40 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
27b50 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
27b60 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
27b70 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
27b80 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
27b90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
27ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27bc0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
27bd0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
27be0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27bf0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
27c00 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
27c10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
27c20 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
27c30 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
27c40 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
27c50 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65  nes provide a me
27c60 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  ans to determine
27c70 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74   the database, t
27c80 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62  able, and.** tab
27c90 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69  le column that i
27ca0 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20  s the origin of 
27cb0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73  a particular res
27cc0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a  ult column in.**
27cd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
27ce0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ent..** ^The nam
27cf0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27d00 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
27d10 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
27d20 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
27d30 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
27d40 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
27d50 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
27d60 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
27d70 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
27d80 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
27d90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
27da0 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
27db0 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
27dc0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27dd0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
27de0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
27df0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
27e00 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
27e10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27e20 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
27e30 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
27e40 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
27e50 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
27e60 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
27e70 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
27e80 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
27e90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27ea0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
27eb0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
27ec0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  * or until the s
27ed0 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
27ee0 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20  is requested.** 
27ef0 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65  again in a diffe
27f00 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rent encoding..*
27f10 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20  *.** ^The names 
27f20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65  returned are the
27f30 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69   original un-ali
27f40 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68  ased names of th
27f50 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74  e.** database, t
27f60 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e  able, and column
27f70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
27f80 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
27f90 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
27fa0 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
27fb0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54  tatement]..** ^T
27fc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
27fd0 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
27fe0 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20  n about the Nth 
27ff0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65  result column re
28000 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65  turned by.** the
28010 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72   statement, wher
28020 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
28030 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  d function argum
28040 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  ent..** ^The lef
28050 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  t-most column is
28060 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68   column 0 for th
28070 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
28080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20  .** ^If the Nth 
28090 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
280a0 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
280b0 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f   is an expressio
280c0 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79  n or.** subquery
280d0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f   and is not a co
280e0 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e  lumn value, then
280f0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75   all of these fu
28100 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a  nctions return.*
28110 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20  * NULL.  ^These 
28120 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
28130 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
28140 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
28150 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
28160 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69  ccurs.  ^Otherwi
28170 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20  se, they return 
28180 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
28190 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
281a0 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20  e, table,.** or 
281b0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72  column that quer
281c0 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  y result column 
281d0 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72  was extracted fr
281e0 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69  om..**.** ^As wi
281f0 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c  th all other SQL
28200 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20  ite APIs, those 
28210 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20  whose names end 
28220 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e  with "16" return
28230 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  .** UTF-16 encod
28240 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74  ed strings and t
28250 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f  he other functio
28260 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e  ns return UTF-8.
28270 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50  .**.** ^These AP
28280 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69  Is are only avai
28290 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62  lable if the lib
282a0 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65  rary was compile
282b0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
282c0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c  QLITE_ENABLE_COL
282d0 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d  UMN_METADATA] C-
282e0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d  preprocessor sym
282f0 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  bol..**.** If tw
28300 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
28310 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
28320 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  re of these rout
28330 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65  ines against the
28340 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65   same.** prepare
28350 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  d statement and 
28360 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61  column at the sa
28370 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
28380 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20   results are.** 
28390 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
283a0 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
283b0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
283c0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c   or more.** [sql
283d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
283e0 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75  base_name | colu
283f0 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65  mn metadata inte
28400 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74  rfaces].** for t
28410 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  he same [prepare
28420 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
28430 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a   result column.*
28440 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  * at the same ti
28450 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
28460 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
28470 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
28480 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
28490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
284a0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  base_name(sqlite
284b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
284c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
284d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
284e0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
284f0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
28500 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
28510 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
28520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
28530 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
28540 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
28550 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
28560 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
28570 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
28580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28590 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
285a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
285b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
285c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
285d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
285e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
285f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28600 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
28610 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
28620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28630 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
28640 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
28650 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
28660 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
28670 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
28680 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
28690 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
286a0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
286b0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
286c0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
286d0 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
286e0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
286f0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
28700 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
28710 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
28720 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
28730 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
28740 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
28750 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
28760 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
28770 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
28780 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
28790 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
287a0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
287b0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
287c0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
287d0 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
287e0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
287f0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
28800 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
28810 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
28820 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
28830 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
28840 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
28850 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
28860 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
28870 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
28880 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
28890 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
288a0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
288b0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
288c0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
288d0 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
288e0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
288f0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
28900 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
28910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
28920 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
28930 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
28940 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
28950 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
28960 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
28970 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
28980 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
28990 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
289a0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
289b0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
289c0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
289d0 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
289e0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
289f0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
28a00 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
28a10 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
28a20 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
28a30 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
28a40 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
28a50 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
28a60 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
28a70 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
28a80 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
28a90 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
28aa0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
28ab0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
28ac0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
28ad0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
28ae0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28af0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28b00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
28b10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
28b20 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
28b30 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
28b40 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
28b50 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
28b60 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ment.**.** After
28b70 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
28b80 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
28b90 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
28ba0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
28bb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28bc0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
28bd0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
28be0 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
28bf0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
28c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28c10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
28c20 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
28c30 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
28c40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
28c50 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
28c60 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
28c70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
28c80 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
28c90 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
28ca0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
28cb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
28cc0 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
28cd0 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
28ce0 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
28cf0 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
28d00 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
28d10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28d20 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
28d30 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28d40 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
28d50 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
28d60 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
28d70 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
28d80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
28d90 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
28da0 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
28db0 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
28dc0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
28dd0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
28de0 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
28df0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
28e00 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
28e10 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
28e20 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
28e30 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
28e40 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
28e50 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
28e60 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
28e70 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
28e80 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
28e90 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
28ea0 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
28eb0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
28ec0 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
28ed0 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
28ee0 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
28ef0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28f00 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
28f10 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
28f20 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
28f30 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
28f40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
28f50 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
28f60 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
28f70 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
28f80 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
28f90 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
28fa0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
28fb0 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
28fc0 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
28fd0 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
28fe0 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
28ff0 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
29000 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
29010 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
29020 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
29030 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
29040 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
29050 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
29060 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
29070 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
29080 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
29090 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
290a0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
290b0 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
290c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
290d0 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
290e0 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
290f0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
29100 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
29110 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
29120 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
29130 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
29140 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
29150 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
29160 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
29170 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
29180 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
29190 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
291a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
291b0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
291c0 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
291d0 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
291e0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
291f0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
29200 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
29210 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
29220 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
29230 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
29240 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
29250 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
29260 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
29270 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
29280 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
29290 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
292a0 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
292b0 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
292c0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
292d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
292e0 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
292f0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
29300 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
29310 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
29320 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
29330 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
29340 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
29350 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
29360 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
29370 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
29380 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
29390 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
293a0 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
293b0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
293c0 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
293d0 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
293e0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
293f0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
29400 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
29410 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
29420 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
29430 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
29440 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
29450 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29460 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
29470 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
29480 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
29490 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
294a0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
294b0 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
294c0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
294d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
294e0 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
294f0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
29500 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
29510 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
29520 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
29530 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
29540 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
29550 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29560 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
29570 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
29580 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
29590 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
295a0 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
295b0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
295c0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
295d0 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
295e0 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
295f0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
29600 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
29610 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29620 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
29630 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
29640 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
29650 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
29660 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
29670 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
29680 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
29690 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
296a0 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
296b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
296c0 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
296d0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
296e0 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
296f0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
29700 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
29710 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
29720 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
29730 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
29740 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
29750 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
29760 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
29770 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
29780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29790 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
297a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
297b0 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
297c0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
297d0 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
297e0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
297f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
29800 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
29810 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
29820 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
29830 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
29840 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
29850 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
29860 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
29870 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
29880 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
29890 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
298a0 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
298b0 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
298c0 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
298d0 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
298e0 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
298f0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
29900 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
29910 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
29920 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
29930 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
29940 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
29950 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
29960 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
29970 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
29980 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
29990 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
299a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
299b0 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
299c0 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
299d0 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
299e0 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
299f0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
29a00 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
29a10 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
29a20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
29a30 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
29a40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29a50 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
29a60 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
29a70 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
29a80 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
29a90 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
29aa0 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
29ab0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
29ac0 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
29ad0 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
29ae0 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
29af0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
29b00 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
29b10 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
29b20 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
29b30 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
29b40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
29b50 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
29b60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29b70 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
29b80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29b90 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
29ba0 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
29bb0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
29bc0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
29bd0 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
29be0 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
29bf0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
29c00 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
29c10 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
29c20 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
29c30 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
29c40 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
29c50 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
29c60 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
29c70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29c80 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
29c90 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
29ca0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
29cb0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
29cc0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
29cd0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29ce0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
29cf0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29d00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29d10 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
29d20 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29d30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
29d40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29d50 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
29d60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
29d70 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
29d80 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
29d90 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
29da0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
29db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
29dc0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
29dd0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
29de0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
29df0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29e00 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
29e10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29e20 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29e30 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
29e40 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
29e50 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
29e60 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29e70 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
29e80 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
29e90 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
29ea0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
29eb0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
29ec0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29ed0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29ee0 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
29ef0 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
29f00 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
29f10 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29f20 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
29f30 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
29f40 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
29f50 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
29f60 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
29f70 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
29f80 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
29f90 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
29fa0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
29fb0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
29fc0 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
29fd0 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
29fe0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29ff0 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
2a000 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  n_count()].*/.SQ
2a010 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a020 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2a030 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2a040 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2a050 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
2a060 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
2a070 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
2a080 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
2a090 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
2a0a0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
2a0b0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
2a0c0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
2a0d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
2a0e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2a0f0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
2a100 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
2a110 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
2a120 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
2a130 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
2a140 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
2a150 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
2a160 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
2a170 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
2a180 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
2a190 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
2a1a0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
2a1b0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
2a1c0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
2a1d0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
2a1e0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
2a1f0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
2a200 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
2a210 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
2a220 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
2a230 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
2a240 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
2a250 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
2a260 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
2a270 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
2a280 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
2a290 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2a2a0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
2a2b0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
2a2c0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2a2d0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
2a2e0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
2a2f0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
2a300 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
2a310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
2a320 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
2a330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
2a340 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
2a350 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
2a360 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
2a370 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
2a380 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
2a390 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
2a3a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a3b0 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
2a3c0 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
2a3d0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
2a3e0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2a3f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2a400 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2a410 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2a420 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2a430 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2a440 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2a450 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2a460 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2a470 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a480 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2a490 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2a4a0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2a4b0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2a4c0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2a4d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a4e0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2a4f0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2a500 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2a510 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2a520 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2a530 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2a540 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2a550 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2a560 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2a570 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2a580 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2a590 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2a5a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2a5b0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2a5c0 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2a5d0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2a5e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2a5f0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2a600 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a610 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2a620 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2a630 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2a640 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2a650 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2a660 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2a670 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2a680 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2a690 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2a6a0 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2a6b0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2a6c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2a6d0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2a6e0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2a6f0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2a700 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2a710 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2a720 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2a730 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2a740 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2a750 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2a760 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2a770 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2a780 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2a790 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2a7a0 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2a7b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2a7c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2a7d0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2a7e0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2a7f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a800 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2a810 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a820 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2a830 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2a840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2a850 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2a860 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2a870 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2a880 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2a890 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2a8a0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2a8b0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2a8c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a8d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2a8e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a8f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2a900 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2a910 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2a920 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2a930 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2a940 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2a950 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2a960 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2a970 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2a980 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2a990 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2a9a0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2a9b0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2a9c0 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2a9d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2a9e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2a9f0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2aa00 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2aa10 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2aa20 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2aa30 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2aa40 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2aa50 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2aa60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2aa70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2aa80 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2aa90 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2aaa0 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2aab0 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2aac0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2aad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2aae0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2aaf0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2ab00 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2ab10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2ab20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2ab30 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2ab40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ab50 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2ab60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ab70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ab80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ab90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2aba0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2abb0 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2abc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2abd0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2abe0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2abf0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2ac00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2ac10 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2ac20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ac30 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2ac40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ac50 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2ac60 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2ac70 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2ac80 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2ac90 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2aca0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2acb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2acc0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2acd0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2ace0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2acf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ad00 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2ad10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2ad20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ad30 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2ad40 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2ad50 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2ad60 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2ad70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2ad80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2ad90 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2ada0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2adb0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2adc0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2add0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2ade0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2adf0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2ae00 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2ae10 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2ae20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ae30 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2ae40 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2ae50 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2ae60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ae70 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2ae80 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2ae90 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2aea0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2aeb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2aec0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2aed0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2aee0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2aef0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2af00 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2af10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2af20 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2af30 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2af40 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2af50 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2af60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2af70 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2af80 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2af90 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2afa0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2afb0 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2afc0 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2afd0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2afe0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2aff0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2b010 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2b020 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2b030 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2b040 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2b050 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2b060 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2b070 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2b080 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2b090 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2b0a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2b0b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b0c0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2b0d0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2b0e0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2b0f0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2b100 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2b110 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2b120 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2b130 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2b140 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2b150 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2b160 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2b170 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2b180 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2b190 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2b1a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b1b0 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
2b1c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b1d0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b1e0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
2b1f0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
2b200 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2b210 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
2b220 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
2b230 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
2b240 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b250 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
2b260 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2b270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2b280 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
2b290 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
2b2a0 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
2b2b0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
2b2c0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
2b2d0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
2b2e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2b2f0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2b300 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
2b310 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b320 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2b330 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2b340 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
2b350 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
2b360 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
2b370 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
2b380 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
2b390 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
2b3a0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
2b3b0 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
2b3c0 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
2b3d0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
2b3e0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
2b3f0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
2b400 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
2b410 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
2b420 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
2b430 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
2b440 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
2b450 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
2b460 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
2b470 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
2b480 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
2b490 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
2b4a0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
2b4b0 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
2b4c0 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
2b4d0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
2b4e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2b4f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2b500 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
2b510 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b520 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
2b530 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2b540 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
2b550 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b560 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
2b570 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b580 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b590 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2b5a0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b5b0 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
2b5c0 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
2b5d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
2b5e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2b5f0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
2b600 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
2b610 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2b620 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
2b630 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b640 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
2b650 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
2b660 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2b670 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
2b680 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
2b690 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
2b6a0 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
2b6b0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
2b6c0 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
2b6d0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
2b6e0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
2b6f0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b700 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2b710 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
2b720 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
2b730 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
2b740 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
2b750 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
2b760 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2b770 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b780 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
2b790 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b7a0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2b7b0 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
2b7c0 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
2b7d0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2b7e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b7f0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
2b800 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2b810 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b820 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
2b830 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
2b840 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
2b850 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
2b860 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
2b870 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
2b880 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
2b890 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b8a0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b8b0 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
2b8c0 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
2b8d0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
2b8e0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
2b8f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
2b900 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
2b910 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
2b920 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
2b930 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
2b940 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
2b950 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
2b960 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
2b970 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
2b980 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
2b990 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
2b9a0 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
2b9b0 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
2b9c0 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
2b9d0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
2b9e0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
2b9f0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
2ba00 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
2ba10 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
2ba20 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
2ba30 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
2ba40 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
2ba50 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
2ba60 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
2ba70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
2ba80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2ba90 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
2baa0 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
2bab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2bac0 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
2bad0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
2bae0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
2baf0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
2bb00 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
2bb10 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
2bb20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
2bb30 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
2bb40 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2bb50 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
2bb60 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
2bb70 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2bb80 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2bb90 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bba0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
2bbb0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
2bbc0 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
2bbd0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
2bbe0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
2bbf0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
2bc00 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
2bc10 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
2bc20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2bc30 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
2bc40 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2bc50 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
2bc60 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
2bc70 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
2bc80 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
2bc90 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
2bca0 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
2bcb0 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
2bcc0 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
2bcd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bce0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
2bcf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd00 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
2bd10 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
2bd20 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2bd30 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
2bd40 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
2bd50 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
2bd60 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
2bd70 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
2bd80 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
2bd90 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
2bda0 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
2bdb0 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
2bdc0 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
2bdd0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
2bde0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
2bdf0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
2be00 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
2be10 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
2be20 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
2be30 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
2be40 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
2be50 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
2be60 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
2be70 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
2be80 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
2be90 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
2bea0 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
2beb0 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
2bec0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
2bed0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
2bee0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
2bef0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
2bf00 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
2bf10 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
2bf20 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
2bf30 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
2bf40 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
2bf50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bf60 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2bf70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2bf80 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
2bf90 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2bfa0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
2bfb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2bfc0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2bfd0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2bfe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2bff0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2c000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c010 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
2c020 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
2c030 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
2c040 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
2c050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
2c060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2c070 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
2c080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c090 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
2c0a0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
2c0b0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
2c0c0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
2c0d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2c0e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
2c0f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
2c100 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
2c110 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
2c120 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
2c130 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
2c140 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
2c150 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
2c160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2c170 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
2c180 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c190 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
2c1a0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
2c1b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2c1c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
2c1d0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
2c1e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c1f0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
2c200 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
2c210 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
2c220 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
2c230 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
2c240 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
2c250 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
2c260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c270 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
2c280 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2c290 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c2a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
2c2b0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
2c2c0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
2c2d0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
2c2e0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
2c2f0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
2c300 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
2c310 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2c320 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
2c330 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
2c340 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c350 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
2c360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
2c370 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
2c380 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2c390 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
2c3a0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
2c3b0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
2c3c0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
2c3d0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
2c3e0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
2c3f0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
2c400 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
2c410 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
2c420 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
2c430 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
2c440 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
2c450 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
2c460 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
2c470 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
2c480 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
2c490 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
2c4a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2c4b0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c4c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
2c4d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c4e0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c4f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c500 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
2c510 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c520 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c530 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2c540 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
2c550 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c560 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c570 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2c580 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
2c590 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c5a0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c5b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c5c0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
2c5d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2c5e0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
2c5f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2c600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
2c610 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2c620 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c630 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2c640 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2c650 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c660 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c670 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c680 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2c690 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2c6a0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2c6b0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c6c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c6d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c6e0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2c6f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2c700 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2c710 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2c720 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2c730 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2c740 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2c750 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2c760 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2c770 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2c780 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2c790 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2c7a0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2c7b0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2c7c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c7d0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2c7e0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2c7f0 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2c800 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2c810 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
2c820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c830 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
2c840 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
2c850 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2c860 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
2c870 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
2c880 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2c890 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
2c8a0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
2c8b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
2c8c0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
2c8d0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
2c8e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
2c8f0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
2c900 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
2c910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2c920 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
2c930 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
2c940 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
2c950 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
2c960 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
2c970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
2c980 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
2c990 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
2c9a0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
2c9b0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
2c9c0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2c9d0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
2c9e0 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
2c9f0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ca00 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
2ca10 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
2ca20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
2ca30 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
2ca40 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
2ca50 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
2ca60 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
2ca70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ca80 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
2ca90 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
2caa0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
2cab0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
2cac0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cad0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
2cae0 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
2caf0 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
2cb00 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
2cb10 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
2cb20 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
2cb30 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
2cb40 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2cb50 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2cb60 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
2cb70 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
2cb80 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
2cb90 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
2cba0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
2cbb0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
2cbc0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
2cbd0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
2cbe0 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
2cbf0 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
2cc00 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  n..*/.SQLITE_API
2cc10 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e   int sqlite3_fin
2cc20 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
2cc30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2cc40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2cc50 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
2cc60 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
2cc70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2cc80 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
2cc90 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
2cca0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
2ccb0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2ccc0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
2ccd0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
2cce0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
2ccf0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
2cd00 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
2cd10 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
2cd20 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
2cd30 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
2cd40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2cd50 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
2cd60 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
2cd70 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
2cd80 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
2cd90 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
2cda0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
2cdb0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
2cdc0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
2cdd0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
2cde0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
2cdf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ce00 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
2ce10 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
2ce20 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
2ce30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
2ce40 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
2ce50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ce60 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
2ce70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ce80 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
2ce90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
2cea0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
2ceb0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
2cec0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
2ced0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
2cee0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
2cef0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
2cf00 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
2cf10 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
2cf20 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2cf30 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2cf40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2cf50 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2cf60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cf70 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
2cf80 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
2cf90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2cfa0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
2cfb0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2cfc0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2cfd0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2cfe0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
2cff0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
2d000 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
2d010 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
2d020 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
2d030 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
2d040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
2d050 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2d060 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
2d070 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d080 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2d090 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
2d0a0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
2d0b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
2d0c0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
2d0d0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
2d0e0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2d0f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d100 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d110 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2d120 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2d130 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2d140 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
2d150 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
2d160 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
2d170 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
2d180 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
2d190 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
2d1a0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
2d1b0 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
2d1c0 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
2d1d0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
2d1e0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
2d1f0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
2d200 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
2d210 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
2d220 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
2d230 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
2d240 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
2d250 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
2d260 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2d270 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
2d280 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
2d290 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
2d2a0 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
2d2b0 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
2d2c0 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
2d2d0 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
2d2e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
2d2f0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2d300 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d310 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
2d320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
2d330 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
2d340 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
2d350 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
2d360 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2d370 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
2d380 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
2d390 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
2d3a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d3b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2d3c0 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
2d3d0 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
2d3e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
2d3f0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
2d400 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2d410 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
2d420 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
2d430 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
2d440 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
2d450 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
2d460 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
2d470 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
2d480 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
2d490 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
2d4a0 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
2d4b0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
2d4c0 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
2d4d0 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
2d4e0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
2d4f0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
2d500 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
2d510 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
2d520 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
2d530 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
2d540 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
2d550 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
2d560 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
2d570 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
2d580 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2d590 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
2d5a0 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
2d5b0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
2d5c0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
2d5d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2d5e0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
2d5f0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
2d600 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
2d610 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
2d620 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
2d630 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
2d640 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
2d650 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
2d660 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
2d670 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
2d680 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
2d690 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2d6a0 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
2d6b0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
2d6c0 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
2d6d0 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
2d6e0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
2d6f0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
2d700 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d710 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
2d720 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
2d730 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
2d740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2d750 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
2d760 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
2d770 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
2d780 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
2d790 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75  s.  Every SQL fu
2d7a0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2d7b0 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62  ation must be ab
2d7c0 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  le to work.** wi
2d7d0 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36  th UTF-8, UTF-16
2d7e0 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e  le, or UTF-16be.
2d7f0 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65    But some imple
2d800 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62  mentations may b
2d810 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69  e.** more effici
2d820 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63  ent with one enc
2d830 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68  oding than anoth
2d840 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61  er.  ^An applica
2d850 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f  tion may.** invo
2d860 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2d870 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20  e_function() or 
2d880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2d890 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74  unction16() mult
2d8a0 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69  iple.** times wi
2d8b0 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  th the same func
2d8c0 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69  tion but with di
2d8d0 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f  fferent values o
2d8e0 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e  f eTextRep..** ^
2d8f0 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d  When multiple im
2d900 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
2d910 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2d920 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65  on are available
2d930 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  , SQLite.** will
2d940 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68   pick the one th
2d950 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20  at involves the 
2d960 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
2d970 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  data conversion.
2d980 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20  .** If there is 
2d990 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d  only a single im
2d9a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69  plementation whi
2d9b0 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  ch does not care
2d9c0 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e   what text.** en
2d9d0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20  coding is used, 
2d9e0 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2d9f0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
2da00 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e  be [SQLITE_ANY].
2da10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66  .**.** ^(The fif
2da20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2da30 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69  an arbitrary poi
2da40 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65  nter.  The imple
2da50 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
2da60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  .** function can
2da70 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20   gain access to 
2da80 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69  this pointer usi
2da90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ng [sqlite3_user
2daa0 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a  _data()].)^.**.*
2dab0 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65  * ^The sixth, se
2dac0 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68  venth and eighth
2dad0 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75   parameters, xFu
2dae0 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46  nc, xStep and xF
2daf0 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69  inal, are.** poi
2db00 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75  nters to C-langu
2db10 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  age functions th
2db20 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
2db30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2db40 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e  .** aggregate. ^
2db50 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
2db60 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
2db70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2db80 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
2db90 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20   callback only; 
2dba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75  NULL pointers mu
2dbb0 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
2dbc0 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46  the xStep and xF
2dbd0 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65  inal.** paramete
2dbe0 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74  rs. ^An aggregat
2dbf0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72  e SQL function r
2dc00 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65  equires an imple
2dc10 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74  mentation of xSt
2dc20 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c  ep.** and xFinal
2dc30 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   and NULL pointe
2dc40 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64  r must be passed
2dc50 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20   for xFunc. ^To 
2dc60 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
2dc70 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
2dc80 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
2dc90 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74   pass NULL point
2dca0 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65  ers for all thre
2dcb0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61  e function.** ca
2dcc0 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e  llbacks..**.** ^
2dcd0 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61  (If the ninth pa
2dce0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2dcf0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2dd00 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e  on_v2() is not N
2dd10 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20  ULL,.** then it 
2dd20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f  is destructor fo
2dd30 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
2dd40 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  n data pointer. 
2dd50 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74  .** The destruct
2dd60 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  or is invoked wh
2dd70 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  en the function 
2dd80 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68  is deleted, eith
2dd90 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f  er by being.** o
2dda0 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65  verloaded or whe
2ddb0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2ddc0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
2ddd0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74  .)^.** ^The dest
2dde0 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69  ructor is also i
2ddf0 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
2de00 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2de10 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2de20 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20  _v2() fails..** 
2de30 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75  ^When the destru
2de40 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ctor callback of
2de50 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d   the tenth param
2de60 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c  eter is invoked,
2de70 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64   it.** is passed
2de80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
2de90 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f  nt which is a co
2dea0 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  py of the applic
2deb0 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70  ation data .** p
2dec0 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73  ointer which was
2ded0 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d   the fifth param
2dee0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2def0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2df00 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  v2()..**.** ^It 
2df10 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
2df20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
2df30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2df40 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
2df50 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
2df60 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2df70 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
2df80 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
2df90 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
2dfa0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
2dfb0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
2dfc0 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20  dings.  ^SQLite 
2dfd0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20  will use.** the 
2dfe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74  implementation t
2dff0 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79  hat most closely
2e000 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79   matches the way
2e010 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a   in which the.**
2e020 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2e030 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74   used.  ^A funct
2e040 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2e050 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65  on with a non-ne
2e060 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70  gative.** nArg p
2e070 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65  arameter is a be
2e080 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  tter match than 
2e090 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  a function imple
2e0a0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a  mentation with.*
2e0b0 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72  * a negative nAr
2e0c0 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  g.  ^A function 
2e0d0 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72  where the prefer
2e0e0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2e0f0 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65  g.** matches the
2e100 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69   database encodi
2e110 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a  ng is a better.*
2e120 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  * match than a f
2e130 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2e140 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  e encoding is di
2e150 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41  fferent.  .** ^A
2e160 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e170 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2e180 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65  ference is betwe
2e190 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55  en UTF16le and U
2e1a0 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63  TF16be.** is a c
2e1b0 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e  loser match than
2e1c0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   a function wher
2e1d0 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2e1e0 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20  ifference is.** 
2e1f0 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64  between UTF8 and
2e200 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42   UTF16..**.** ^B
2e210 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e  uilt-in function
2e220 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61  s may be overloa
2e230 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69  ded by new appli
2e240 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2e250 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  unctions..**.** 
2e260 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  ^An application-
2e270 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2e280 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2e290 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53   call other.** S
2e2a0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2e2b0 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68  .  However, such
2e2c0 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a   calls must not.
2e2d0 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ** close the dat
2e2e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e2f0 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72   nor finalize or
2e300 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2e310 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2e320 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75   in which the fu
2e330 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2e340 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
2e350 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2e360 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
2e370 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
2e380 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
2e390 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
2e3a0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
2e3b0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
2e3c0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
2e3d0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
2e3e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e3f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e400 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
2e410 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
2e420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
2e430 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
2e440 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
2e450 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
2e460 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2e470 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2e480 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2e490 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2e4a0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
2e4b0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
2e4c0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
2e4d0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
2e4e0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
2e4f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2e500 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2e510 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
2e520 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e530 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e540 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e550 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
2e560 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49  ontext*).);.SQLI
2e570 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2e580 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e590 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2e5a0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2e5b0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2e5c0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2e5d0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2e5e0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2e5f0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2e600 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2e610 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2e620 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2e630 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2e640 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e650 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e660 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2e670 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2e680 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2e690 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2e6a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2e6b0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2e6c0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2e6d0 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2e6e0 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2e6f0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2e700 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2e710 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2e720 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2e730 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2e740 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2e750 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2e760 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2e770 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2e780 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2e790 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2e7a0 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2e7b0 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2e7c0 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2e7d0 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2e7e0 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2e7f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e800 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2e810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2e820 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2e830 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2e840 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2e850 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2e860 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2e870 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2e880 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2e890 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2e8a0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2e8b0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2e8c0 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2e8d0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2e8e0 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2e8f0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2e900 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2e910 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2e920 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2e930 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2e940 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2e950 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2e960 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2e970 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2e980 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2e990 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2e9a0 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2e9b0 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2e9c0 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2e9d0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2e9e0 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2e9f0 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  ED.SQLITE_API SQ
2ea00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2ea10 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
2ea20 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
2ea30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
2ea40 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
2ea50 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2ea60 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28  sqlite3_expired(
2ea70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2ea80 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2ea90 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2eaa0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
2eab0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
2eac0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
2ead0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2eae0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
2eaf0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2eb00 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2eb10 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2eb20 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2eb30 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
2eb40 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75  e3_thread_cleanu
2eb50 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  p(void);.SQLITE_
2eb60 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
2eb70 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2eb80 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
2eb90 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2eba0 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
2ebb0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
2ebc0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
2ebd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
2ebe0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
2ebf0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
2ec00 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
2ec10 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
2ec20 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
2ec30 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
2ec40 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
2ec50 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
2ec60 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
2ec70 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
2ec80 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
2ec90 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
2eca0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
2ecb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
2ecc0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
2ecd0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
2ece0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
2ecf0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
2ed00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
2ed10 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
2ed20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2ed30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2ed40 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
2ed50 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
2ed60 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
2ed70 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2ed80 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
2ed90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
2eda0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
2edb0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
2edc0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
2edd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ede0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
2edf0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
2ee00 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2ee10 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
2ee20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2ee30 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
2ee40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2ee50 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
2ee60 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
2ee70 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
2ee80 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
2ee90 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2eea0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
2eeb0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
2eec0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2eed0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
2eee0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
2eef0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
2ef00 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2ef10 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
2ef20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
2ef30 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
2ef40 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
2ef50 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
2ef60 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
2ef70 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
2ef80 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2ef90 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
2efa0 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
2efb0 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
2efc0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
2efd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2efe0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
2eff0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
2f000 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
2f010 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
2f020 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
2f030 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
2f040 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f050 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
2f060 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
2f070 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
2f080 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
2f090 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
2f0a0 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
2f0b0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
2f0c0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
2f0d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f0e0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
2f0f0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
2f100 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
2f110 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
2f120 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
2f130 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
2f140 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
2f150 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2f160 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
2f170 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
2f180 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
2f190 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
2f1a0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
2f1b0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
2f1c0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
2f1d0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
2f1e0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
2f1f0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
2f200 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
2f210 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
2f220 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
2f230 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
2f240 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
2f250 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
2f260 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
2f270 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
2f280 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
2f290 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
2f2a0 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
2f2b0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
2f2c0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
2f2d0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
2f2e0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
2f2f0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
2f300 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
2f310 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
2f320 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
2f330 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
2f340 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
2f350 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
2f360 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
2f370 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
2f380 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f390 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
2f3a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2f3b0 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
2f3c0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
2f3d0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
2f3e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2f3f0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
2f400 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
2f410 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2f420 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
2f430 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
2f440 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
2f450 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2f460 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
2f470 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
2f480 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
2f490 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
2f4a0 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
2f4b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
2f4c0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53  parameters..*/.S
2f4d0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f4e0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2f4f0 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2f500 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2f510 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2f520 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c  _value_bytes(sql
2f530 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f540 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f550 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f560 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2f570 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  *);.SQLITE_API d
2f580 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
2f590 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
2f5a0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f5b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f5c0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
2f5d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f5e0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
2f5f0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2f600 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2f610 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f620 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
2f630 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2f640 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
2f650 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f660 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2f670 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2f680 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
2f690 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2f6a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2f6b0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2f6c0 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  e_text16le(sqlit
2f6d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f6e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f6f0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2f700 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2f710 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2f720 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2f730 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
2f740 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f750 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f760 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
2f770 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
2f780 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
2f790 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2f7a0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
2f7b0 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
2f7c0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
2f7d0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
2f7e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
2f7f0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
2f800 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
2f810 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
2f820 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
2f830 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
2f840 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
2f850 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2f860 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
2f870 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
2f880 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
2f890 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
2f8a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
2f8b0 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
2f8c0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
2f8d0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
2f8e0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
2f8f0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
2f900 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
2f910 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
2f920 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2f930 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2f940 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
2f950 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2f960 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2f970 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
2f980 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
2f990 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
2f9a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
2f9b0 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
2f9c0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
2f9d0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
2f9e0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
2f9f0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
2fa00 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
2fa10 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
2fa20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
2fa30 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
2fa40 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
2fa50 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
2fa60 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
2fa70 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
2fa80 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
2fa90 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2faa0 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
2fab0 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
2fac0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
2fad0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
2fae0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
2faf0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2fb00 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
2fb10 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
2fb20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
2fb30 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
2fb40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
2fb50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2fb60 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2fb70 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
2fb80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e  ULL pointer if N
2fb90 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
2fba0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
2fbb0 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
2fbc0 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
2fbd0 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
2fbe0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
2fbf0 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
2fc00 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2fc10 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2fc20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
2fc30 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
2fc40 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
2fc50 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
2fc60 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
2fc70 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
2fc80 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
2fc90 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fca0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
2fcb0 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
2fcc0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2fcd0 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
2fce0 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
2fcf0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
2fd00 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ion.)^.**.** ^SQ
2fd10 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
2fd20 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d  ly frees the mem
2fd30 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ory allocated by
2fd40 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67   .** sqlite3_agg
2fd50 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2fd60 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67   when the aggreg
2fd70 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75  ate query conclu
2fd80 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  des..**.** The f
2fd90 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d  irst parameter m
2fda0 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66  ust be a copy of
2fdb0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2fdc0 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66  _context | SQL f
2fdd0 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d  unction context]
2fde0 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72   that is the fir
2fdf0 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st parameter.** 
2fe00 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20  to the xStep or 
2fe10 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
2fe20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70  routine that imp
2fe30 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72  lements the aggr
2fe40 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  egate.** functio
2fe50 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2fe60 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2fe70 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2fe80 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2fe90 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67  ch.** the aggreg
2fea0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2feb0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2fec0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2fed0 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
2fee0 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
2fef0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2ff00 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
2ff10 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
2ff20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
2ff30 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2ff40 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2ff50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ff60 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
2ff70 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61   the pointer tha
2ff80 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44  t was the pUserD
2ff90 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74  ata parameter (t
2ffa0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2ffb0 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2ffc0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2ffd0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2ffe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fff0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
30000 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
30010 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
30020 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
30030 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
30040 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
30050 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
30060 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
30070 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
30080 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70  which.** the app
30090 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
300a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
300b0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
300c0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
300d0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
300e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
300f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30100 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
30110 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
30120 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
30130 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
30140 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
30150 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
30160 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
30170 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
30180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30190 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
301a0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
301b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
301c0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
301d0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
301e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
301f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
30200 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
30210 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
30220 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
30230 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  unction..*/.SQLI
30240 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a  TE_API sqlite3 *
30250 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
30260 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
30270 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
30280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
30290 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
302a0 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Data.**.** The 
302b0 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75  following two fu
302c0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
302d0 73 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51  sed by scalar SQ
302e0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a  L functions to.*
302f0 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61  * associate meta
30300 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65  data with argume
30310 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68  nt values. If th
30320 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20  e same value is 
30330 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c  passed to.** mul
30340 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e  tiple invocation
30350 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51  s of the same SQ
30360 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e  L function durin
30370 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f  g query executio
30380 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65  n, under.** some
30390 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74   circumstances t
303a0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65  he associated me
303b0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72  tadata may be pr
303c0 65 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61  eserved. This ma
303d0 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f  y.** be used, fo
303e0 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64  r example, to ad
303f0 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  d a regular-expr
30400 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20  ession matching 
30410 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69  scalar.** functi
30420 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64  on. The compiled
30430 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
30440 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
30450 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a  on is stored as.
30460 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
30470 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
30480 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64  SQL value passed
30490 20 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20   as the regular 
304a0 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61  expression.** pa
304b0 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70  ttern.  The comp
304c0 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
304d0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
304e0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
304f0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
30500 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
30510 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68  ction so that th
30520 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65  e original patte
30530 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65  rn string.** doe
30540 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
30550 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65   recompiled on e
30560 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a  ach invocation..
30570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30580 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
30590 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
305a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
305b0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
305c0 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68  associated by th
305d0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
305e0 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e  xdata() function
305f0 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72   with the Nth ar
30600 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20  gument.** value 
30610 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
30620 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
30630 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61  ion. ^If no meta
30640 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76  data has been ev
30650 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66  er.** been set f
30660 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  or the Nth argum
30670 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ent of the funct
30680 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63  ion, or if the c
30690 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
306a0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
306b0 65 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73  er has changed s
306c0 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61  ince the meta-da
306d0 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74  ta was set,.** t
306e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hen sqlite3_get_
306f0 61 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e  auxdata() return
30700 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30720 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
30730 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76  () interface sav
30740 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  es the metadata.
30750 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
30760 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
30770 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61  er as the metada
30780 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
30790 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
307a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
307b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
307c0 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20    Subsequent.** 
307d0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
307e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d  _get_auxdata() m
307f0 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73  ight return this
30800 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73   data, if it has
30810 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73  .** not been des
30820 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69  troyed..** ^If i
30830 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
30840 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
30850 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
30860 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
30870 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
30880 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
30890 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
308a0 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
308b0 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
308c0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
308d0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
308e0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
308f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
30900 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
30910 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
30920 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
30930 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
30940 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
30950 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
30960 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
30970 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
30980 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
30990 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67  me.  ^The only g
309a0 75 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74  uarantee is that
309b0 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74  .** the destruct
309c0 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  or will be calle
309d0 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74  d before the met
309e0 61 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64  adata is dropped
309f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
30a00 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
30a10 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
30a20 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
30a30 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65  lls for.** expre
30a40 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ssions that are 
30a50 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70  constant at comp
30a60 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69  ile time. This i
30a70 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a  ncludes literal.
30a80 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
30a90 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a  arameters].)^.**
30aa0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
30ab0 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
30ac0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
30ad0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
30ae0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
30af0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
30b00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
30b10 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
30b20 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
30b30 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
30b40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
30b50 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
30b60 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
30b70 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
30b80 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
30b90 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
30ba0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
30bb0 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
30bc0 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
30bd0 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
30be0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
30bf0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
30c00 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
30c10 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
30c20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
30c30 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
30c40 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
30c50 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
30c60 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
30c70 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
30c80 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
30c90 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
30ca0 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
30cb0 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
30cc0 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
30cd0 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
30ce0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
30cf0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
30d00 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
30d10 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
30d20 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
30d30 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
30d40 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
30d50 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
30d60 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
30d70 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
30d80 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
30d90 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
30da0 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
30db0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
30dc0 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
30dd0 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
30de0 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
30df0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
30e00 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
30e10 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
30e20 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
30e30 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
30e40 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
30e50 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
30e60 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
30e70 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
30e80 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
30e90 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
30ea0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
30eb0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
30ec0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
30ed0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
30ee0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
30ef0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
30f00 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
30f10 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
30f20 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
30f30 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
30f40 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
30f50 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
30f60 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
30f70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30f80 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
30f90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
30fa0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
30fb0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
30fc0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
30fd0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
30fe0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
30ff0 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
31000 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
31010 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
31020 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
31030 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
31040 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
31050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
31060 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
31070 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
31080 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
31090 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
310a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
310b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
310c0 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
310d0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
310e0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
310f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31100 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
31110 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
31120 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
31130 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
31140 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
31150 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
31160 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
31170 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
31180 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
31190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
311a0 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
311b0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
311c0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
311d0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
311e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
311f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
31200 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
31210 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
31220 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
31230 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
31240 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31250 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
31260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31270 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
31280 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31290 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
312a0 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
312b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
312c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
312d0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
312e0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
312f0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
31300 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
31310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31320 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
31330 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31340 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
31350 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
31360 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
31370 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
31380 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
31390 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
313a0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
313b0 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
313c0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
313d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
313e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
313f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
31400 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
31410 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
31420 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
31430 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
31440 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
31450 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
31460 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
31470 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
31480 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
31490 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
314a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
314b0 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
314c0 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
314d0 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
314e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
314f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
31500 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
31510 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31520 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
31530 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
31540 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
31550 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
31560 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
31570 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
31580 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
31590 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
315a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
315b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
315c0 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
315d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
315e0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
315f0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
31600 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
31610 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
31620 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
31630 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31640 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
31650 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
31660 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31670 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
31680 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
31690 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
316a0 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
316b0 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
316c0 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
316d0 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
316e0 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
316f0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
31700 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
31710 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
31720 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
31730 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
31740 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
31750 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31760 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
31770 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
31780 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
31790 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
317a0 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
317b0 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
317c0 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
317d0 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
317e0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
317f0 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
31800 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
31810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
31820 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
31830 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31840 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
31850 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
31860 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
31870 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31880 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
31890 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
318a0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
318b0 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
318c0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
318d0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
318e0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
318f0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
31900 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31910 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
31920 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
31930 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
31940 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
31950 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
31960 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
31970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31980 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
31990 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
319a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
319b0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
319c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
319d0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
319e0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
319f0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
31a00 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
31a10 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
31a20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31a30 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
31a40 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
31a50 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
31a60 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
31a70 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
31a80 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
31a90 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
31aa0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
31ab0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
31ac0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
31ad0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31ae0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
31af0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
31b00 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
31b10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31b20 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31b30 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
31b40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
31b50 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
31b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31b70 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
31b80 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
31b90 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
31ba0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
31bb0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
31bc0 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
31bd0 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
31be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31bf0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
31c00 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
31c10 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
31c20 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
31c30 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
31c40 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
31c50 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
31c60 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
31c70 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
31c80 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
31c90 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
31ca0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
31cb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
31cc0 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
31cd0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
31ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31cf0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
31d00 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
31d10 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31d30 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
31d40 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
31d50 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
31d60 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
31d70 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31d80 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
31d90 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
31da0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
31db0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31dc0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
31dd0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
31de0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
31df0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
31e00 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
31e10 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
31e20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
31e30 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
31e40 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
31e50 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
31e60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
31e70 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
31e80 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20  result.  If the 
31e90 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  3rd parameter is
31ea0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31eb0 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62  hen it.** must b
31ec0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
31ed0 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e  t into the strin
31ee0 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  g where the NUL 
31ef0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
31f00 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68  .** appear if th
31f10 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e  e string where N
31f20 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  UL terminated.  
31f30 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
31f40 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69  cters occur.** i
31f50 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20  n the string at 
31f60 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68  a byte offset th
31f70 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  at is less than 
31f80 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
31f90 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65   3rd.** paramete
31fa0 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  r, then the resu
31fb0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c  lting string wil
31fc0 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  l contain embedd
31fd0 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a  ed NULs and the.
31fe0 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70  ** result of exp
31ff0 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69  ressions operati
32000 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69  ng on strings wi
32010 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  th embedded NULs
32020 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
32030 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
32040 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
32050 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
32060 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
32070 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
32080 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
32090 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
320a0 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
320b0 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
320c0 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
320d0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
320e0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
320f0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
32100 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
32110 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
32120 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
32130 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
32140 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
32150 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
32160 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
32170 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
32180 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
32190 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
321a0 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
321b0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
321c0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
321d0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
321e0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
321f0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
32200 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
32210 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
32220 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
32230 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
32240 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
32250 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
32260 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
32270 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
32280 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
32290 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
322a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
322b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
322c0 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
322d0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
322e0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
322f0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
32300 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
32310 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
32320 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
32330 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
32340 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
32350 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
32360 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32370 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
32380 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
32390 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
323a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
323b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
323c0 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
323d0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
323e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
323f0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
32400 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
32410 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
32420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32430 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
32440 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
32450 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
32460 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
32470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
32480 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
32490 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
324a0 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
324b0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
324c0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
324d0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
324e0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
324f0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
32500 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32510 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
32520 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
32530 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
32540 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32550 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
32560 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
32570 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
32580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
32590 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
325a0 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
325b0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
325c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
325d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
325e0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
325f0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
32600 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
32610 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
32620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
32630 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
32640 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
32650 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
32660 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
32670 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
32680 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
32690 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
326a0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
326b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
326c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
326d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
326e0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
326f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
32700 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
32710 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
32720 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
32740 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
32750 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
32760 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
32770 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32780 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
32790 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
327a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
327b0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
327c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
327d0 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
327e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
327f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32800 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32810 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
32820 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32830 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32850 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
32860 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32870 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32880 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32890 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
328a0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
328b0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
328c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
328d0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
328e0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
328f0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
32900 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32910 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
32920 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
32930 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32940 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
32950 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32960 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
32970 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32980 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
32990 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
329a0 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
329b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
329c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
329d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
329e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
329f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
32a00 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
32a10 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
32a20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
32a30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
32a40 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
32a50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
32a60 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
32a70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
32a80 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
32a90 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
32aa0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
32ab0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
32ac0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
32ad0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
32ae0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
32b00 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
32b10 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
32b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32b30 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
32b40 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
32b50 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
32b60 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
32b70 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
32b80 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
32b90 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
32ba0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
32bb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
32bc0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
32bd0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
32be0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
32bf0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
32c00 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
32c10 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
32c20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
32c30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
32c40 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
32c50 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
32c60 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
32c70 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
32c80 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
32c90 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
32ca0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
32cb0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
32cc0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
32cd0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
32ce0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
32cf0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
32d00 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
32d10 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
32d20 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
32d30 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
32d40 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
32d50 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
32d60 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
32d70 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
32d80 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
32d90 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
32da0 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
32db0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
32dc0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
32dd0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
32de0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
32df0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
32e00 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
32e10 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
32e20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
32e30 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
32e40 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32e50 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
32e60 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
32e70 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
32e80 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
32e90 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
32ea0 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
32eb0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
32ec0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
32ed0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
32ee0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
32ef0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
32f00 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
32f10 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
32f20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
32f30 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
32f40 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
32f50 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
32f60 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70   pArg, is an app
32f70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32f80 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
32f90 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20  ssed.** through 
32fa0 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
32fb0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c  ument to the col
32fc0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
32fd0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
32fe0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
32ff0 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20  ent, xCallback, 
33000 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
33010 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33020 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74  nction..** ^Mult
33030 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  iple collating f
33040 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20  unctions can be 
33050 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67  registered using
33060 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
33070 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65  ut.** with diffe
33080 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61  rent eTextRep pa
33090 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c  rameters and SQL
330a0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69  ite will use whi
330b0 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69  chever.** functi
330c0 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20  on requires the 
330d0 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20  least amount of 
330e0 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74  data transformat
330f0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
33100 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65  xCallback argume
33110 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  nt is NULL then 
33120 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
33130 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c  nction is.** del
33140 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c  eted.  ^When all
33150 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33160 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20  ions having the 
33170 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65  same name are de
33180 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63  leted,.** that c
33190 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  ollation is no l
331a0 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a  onger usable..**
331b0 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69  .** ^The collati
331c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
331d0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
331e0 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74  with a copy of t
331f0 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c  he pArg .** appl
33200 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
33210 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77  nter and with tw
33220 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  o strings in the
33230 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
33240 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54  ied.** by the eT
33250 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e  extRep argument.
33260 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20    The collating 
33270 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65  function must re
33280 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  turn an.** integ
33290 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74  er that is negat
332a0 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f  ive, zero, or po
332b0 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65  sitive.** if the
332c0 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73   first string is
332d0 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61   less than, equa
332e0 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72  l to, or greater
332f0 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64   than the second
33300 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
33310 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20  y.  A collating 
33320 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c  function must al
33330 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
33340 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67  same answer.** g
33350 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e  iven the same in
33360 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72  puts.  If two or
33370 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20   more collating 
33380 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65  functions are re
33390 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74  gistered.** to t
333a0 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f  he same collatio
333b0 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69  n name (using di
333c0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
333d0 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c   values) then al
333e0 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61  l.** must give a
333f0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73  n equivalent ans
33400 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64  wer when invoked
33410 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74   with equivalent
33420 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
33430 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
33440 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68  ion must obey th
33450 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70  e following prop
33460 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a  erties for all.*
33470 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20  * strings A, B, 
33480 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c  and C:.**.** <ol
33490 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d  >.** <li> If A==
334a0 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20  B then B==A..** 
334b0 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64  <li> If A==B and
334c0 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e   B==C then A==C.
334d0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
334e0 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a  ;B THEN B&gt;A..
334f0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
33500 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65  B and B&lt;C the
33510 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f  n A&lt;C..** </o
33520 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f  l>.**.** If a co
33530 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
33540 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68   fails any of th
33550 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69  e above constrai
33560 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20  nts and that.** 
33570 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33580 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65  on is  registere
33590 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e  d and used, then
335a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
335b0 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e   SQLite.** is un
335c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
335d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
335e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
335f0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
33600 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33610 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20  ation().** with 
33620 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61  the addition tha
33630 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63  t the xDestroy c
33640 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
33650 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a  ed on pArg when.
33660 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** the collating
33670 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
33680 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74  eted..** ^Collat
33690 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
336a0 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  e deleted when t
336b0 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64  hey are overridd
336c0 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63  en by later.** c
336d0 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c  alls to the coll
336e0 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66  ation creation f
336f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e  unctions or when
33700 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
33710 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
33720 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73   closed using [s
33730 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e  qlite3_close()].
33740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73  .**.** ^The xDes
33750 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
33760 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c   <u>not</u> call
33770 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71  ed if the .** sq
33780 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
33790 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63  lation_v2() func
337a0 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70  tion fails.  App
337b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69  lications that i
337c0 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
337d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
337e0 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f  n_v2() with a no
337f0 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20  n-NULL xDestroy 
33800 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
33810 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65  .** check the re
33820 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69  turn code and di
33830 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70  spose of the app
33840 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33850 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c  inter.** themsel
33860 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20  ves rather than 
33870 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65  expecting SQLite
33880 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74   to deal with it
33890 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68   for them..** Th
338a0 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20  is is different 
338b0 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72  from every other
338c0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
338d0 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73  e.  The inconsis
338e0 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66  tency .** is unf
338f0 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e  ortunate but can
33900 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77  not be changed w
33910 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
33920 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f  backwards .** co
33930 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a  mpatibility..**.
33940 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73  ** See also:  [s
33950 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
33960 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b  _needed()] and [
33970 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33980 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a  n_needed16()]..*
33990 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
339a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
339b0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
339c0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
339d0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
339e0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
339f0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
33a00 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
33a10 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33a20 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
33a30 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  id*).);.SQLITE_A
33a40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
33a50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
33a60 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
33a70 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33a80 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
33a90 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
33aa0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
33ab0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
33ac0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
33ad0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20  ,const void*),. 
33ae0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
33af0 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54  (void*).);.SQLIT
33b00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
33b10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33b20 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
33b30 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
33b40 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
33b50 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
33b60 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
33b70 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
33b80 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
33b90 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
33ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33bb0 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65  F: Collation Nee
33bc0 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ded Callbacks.**
33bd0 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61  .** ^To avoid ha
33be0 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72  ving to register
33bf0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73   all collation s
33c00 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20  equences before 
33c10 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61  a database.** ca
33c20 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e  n be used, a sin
33c30 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  gle callback fun
33c40 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
33c50 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65  istered with the
33c60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
33c70 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20  nnection] to be 
33c80 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
33c90 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   an undefined co
33ca0 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
33cb0 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64 2e  nce is required.
33cc0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
33cd0 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73  unction is regis
33ce0 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  tered using the 
33cf0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33d00 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a  n_needed() API,.
33d10 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70 61  ** then it is pa
33d20 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f  ssed the names o
33d30 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  f undefined coll
33d40 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
33d50 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e  as strings.** en
33d60 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20  coded in UTF-8. 
33d70 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  ^If sqlite3_coll
33d80 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
33d90 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
33da0 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
33db0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
33dc0 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
33dd0 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20  te order..** ^A 
33de0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66  call to either f
33df0 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73  unction replaces
33e00 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f   the existing co
33e10 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63  llation-needed c
33e20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
33e30 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  (When the callba
33e40 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74  ck is invoked, t
33e50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
33e60 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63 6f  t passed is a co
33e70 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63  py.** of the sec
33e80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
33e90 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
33ea0 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a  n_needed() or.**
33eb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33ec0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20  on_needed16().  
33ed0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
33ee0 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61 62  ent is the datab
33ef0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
33f00 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  n.  The third ar
33f10 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
33f20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
33f30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
33f40 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ,.** or [SQLITE_
33f50 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61  UTF16LE], indica
33f60 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65  ting the most de
33f70 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20  sirable form of 
33f80 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  the collation.**
33f90 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69   sequence functi
33fa0 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54 68  on required.  Th
33fb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
33fc0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
33fd0 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65  f the.** require
33fe0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
33ff0 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  ence.)^.**.** Th
34000 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
34010 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73  ion should regis
34020 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64 20  ter the desired 
34030 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a  collation using.
34040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
34050 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c  te_collation()],
34060 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34070 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c  _collation16()],
34080 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34090 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
340a0 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
340b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
340c0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
340d0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
340e0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
340f0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
34100 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
34110 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
34120 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34130 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34140 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
34150 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
34160 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
34170 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
34180 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
34190 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20  id*).);..#ifdef 
341a0 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43  SQLITE_HAS_CODEC
341b0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
341c0 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e  he key for an en
341d0 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73 65  crypted database
341e0 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  .  This routine 
341f0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c  should be.** cal
34200 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72 20  led right after 
34210 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a  sqlite3_open()..
34220 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
34230 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
34240 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
34250 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
34260 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
34270 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
34280 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34290 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74  te3_key(.  sqlit
342a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
342b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
342c0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
342d0 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
342e0 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
342f0 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b  Key     /* The k
34300 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
34310 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f  Change the key o
34320 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  n an open databa
34330 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72  se.  If the curr
34340 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20  ent database is 
34350 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64  not.** encrypted
34360 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  , this routine w
34370 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20  ill encrypt it. 
34380 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e   If pNew==0 or n
34390 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64  New==0, the.** d
343a0 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79  atabase is decry
343b0 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  pted..**.** The 
343c0 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
343d0 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
343e0 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
343f0 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
34400 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
34410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34420 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
34430 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
34440 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34450 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
34460 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
34470 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
34480 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
34490 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
344a0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63  /.);../*.** Spec
344b0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
344c0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45  on key for a SEE
344d0 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
344e0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
344f0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45  , none of the SE
34500 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  E routines will 
34510 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
34520 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
34530 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
34540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
34550 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
34560 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
34570 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
34580 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
34590 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
345a0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
345b0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
345c0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
345d0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
345e0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
345f0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
34600 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
34610 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34620 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
34630 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
34640 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
34650 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
34660 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
34670 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
34680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34690 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
346a0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
346b0 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
346c0 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
346d0 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
346e0 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
346f0 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
34700 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
34710 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
34720 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
34730 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
34740 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
34750 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
34760 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
34770 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
34780 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
34790 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
347a0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
347b0 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
347c0 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
347d0 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
347e0 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
347f0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34800 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
34810 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
34820 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
34830 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
34840 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
34850 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
34860 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
34870 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
34880 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
34890 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
348a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
348b0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
348c0 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
348d0 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
348e0 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
348f0 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
34900 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
34910 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
34920 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
34930 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34940 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
34950 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
34960 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
34970 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
34980 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54  graphs..*/.SQLIT
34990 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
349a0 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
349b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
349c0 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
349d0 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
349e0 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
349f0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
34a00 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
34a10 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
34a20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
34a30 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
34a40 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
34a50 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
34a60 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
34a70 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
34a80 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
34a90 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
34aa0 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
34ab0 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
34ac0 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
34ad0 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
34ae0 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
34af0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
34b00 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
34b10 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
34b20 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
34b30 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
34b40 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
34b50 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
34b60 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
34b70 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
34b80 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
34b90 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
34ba0 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
34bb0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
34bc0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
34bd0 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
34be0 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
34bf0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
34c00 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
34c10 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
34c20 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
34c30 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
34c40 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
34c50 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
34c60 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
34c70 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
34c80 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
34c90 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
34ca0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
34cb0 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
34cc0 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
34cd0 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
34ce0 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
34cf0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
34d00 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
34d10 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34d20 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
34d30 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
34d40 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
34d50 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
34d60 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34d70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34d80 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
34d90 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
34da0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34db0 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
34dc0 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
34dd0 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
34de0 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
34df0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
34e00 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
34e10 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
34e20 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
34e30 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
34e40 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
34e50 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
34e60 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
34e70 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
34e80 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
34e90 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
34ea0 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
34eb0 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
34ec0 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
34ed0 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
34ee0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
34ef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
34f00 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
34f10 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
34f20 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
34f30 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
34f40 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
34f50 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58  TE_API SQLITE_EX
34f60 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
34f70 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
34f80 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
34f90 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
34fa0 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
34fb0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
34fc0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
34fd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34fe0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
34ff0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35000 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
35010 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
35020 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
35030 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
35040 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
35050 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
35060 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
35070 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
35080 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
35090 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
350a0 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
350b0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
350c0 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
350d0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
350e0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
350f0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
35100 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
35110 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
35120 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
35130 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
35140 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
35150 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
35160 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
35170 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
35180 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
35190 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
351a0 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
351b0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
351c0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
351d0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
351e0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
351f0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
35200 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
35210 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
35220 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
35230 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
35240 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
35250 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
35260 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
35270 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
35280 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35290 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
352a0 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
352b0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
352c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
352d0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
352e0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
352f0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
35300 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
35310 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
35320 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
35330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67  PI int sqlite3_g
35340 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71  et_autocommit(sq
35350 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
35360 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54  CAPI3REF: Find T
35370 68 65 20 44 61 74 61 62 61 73 65 20 48 61 6e 64  he Database Hand
35380 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72 65 64  le Of A Prepared
35390 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
353a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
353b0 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63  _handle interfac
353c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64  e returns the [d
353d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
353e0 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f  on] handle.** to
353f0 20 77 68 69 63 68 20 61 20 5b 70 72 65 70 61 72   which a [prepar
35400 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65  ed statement] be
35410 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61  longs.  ^The [da
35420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35430 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  n].** returned b
35440 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  y sqlite3_db_han
35450 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  dle is the same 
35460 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35470 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tion].** that wa
35480 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
35490 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
354a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
354b0 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69  v2()] call (or i
354c0 74 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61  ts variants) tha
354d0 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a  t was used to.**
354e0 20 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74   create the stat
354f0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72  ement in the fir
35500 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c  st place..*/.SQL
35510 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
35520 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64  *sqlite3_db_hand
35530 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
35540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35550 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65 20 46  EF: Return The F
35560 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20 44 61  ilename For A Da
35570 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
35580 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
35590 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61 6d 65  ite3_db_filename
355a0 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (D,N) interface 
355b0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
355c0 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d 65 0a  r to a filename.
355d0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
355e0 74 68 20 64 61 74 61 62 61 73 65 20 4e 20 6f 66  th database N of
355f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
35600 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61  ^The main databa
35610 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73 20 74  se file.** has t
35620 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22 2e 20  he name "main". 
35630 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
35640 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
35650 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74 61 62  e N on the datab
35660 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
35670 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74 61 62  n D, or if datab
35680 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d 70 6f  ase N is a tempo
35690 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d 6f 72  rary or in-memor
356a0 79 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 6e  y database, then
356b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
356c0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
356d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c 65 6e  **.** ^The filen
356e0 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  ame returned by 
356f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  this function is
35700 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 74   the output of t
35710 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74 68 6e  he.** xFullPathn
35720 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ame method of th
35730 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20 6f 74  e [VFS].  ^In ot
35740 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 66  her words, the f
35750 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  ilename.** will 
35760 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  be an absolute p
35770 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20 69 66  athname, even if
35780 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 75 73   the filename us
35790 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20 74 68  ed.** to open th
357a0 65 20 64 61 74 61 62 61 73 65 20 6f 72 69 67 69  e database origi
357b0 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52 49 20  nally was a URI 
357c0 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61 74 68  or relative path
357d0 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  name..*/.SQLITE_
357e0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
357f0 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e  sqlite3_db_filen
35800 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ame(sqlite3 *db,
35810 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
35820 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
35830 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
35840 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
35850 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 0a  is read-only.**.
35860 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35870 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c 4e 29  db_readonly(D,N)
35880 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35890 6e 73 20 31 20 69 66 20 74 68 65 20 64 61 74 61  ns 1 if the data
358a0 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63 6f 6e  base N.** of con
358b0 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72 65 61  nection D is rea
358c0 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69 74 20  d-only, 0 if it 
358d0 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c 20 6f  is read/write, o
358e0 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e 6f 74  r -1 if N is not
358f0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
35900 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 63 6f  a database on co
35910 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f 0a 53  nnection D..*/.S
35920 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35930 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
35940 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 63  y(sqlite3 *db, c
35950 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
35960 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
35970 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e  3REF: Find the n
35980 65 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61  ext prepared sta
35990 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
359a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
359b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
359c0 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
359d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
359e0 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
359f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35a00 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35a10 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e  nection] pDb.  ^
35a20 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c  If pStmt is NULL
35a30 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e  .** then this in
35a40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35a50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
35a60 20 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20   first prepared 
35a70 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73  statement.** ass
35a80 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
35a90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35aa0 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e  tion pDb.  ^If n
35ab0 6f 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  o prepared state
35ac0 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65  ment.** satisfie
35ad0 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73  s the conditions
35ae0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
35af0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c  , it returns NUL
35b00 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61  L..**.** The [da
35b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35b20 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20  n] pointer D in 
35b30 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
35b40 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35b50 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72  D,S)] must refer
35b60 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   to an open data
35b70 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
35b80 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63  on and in partic
35b90 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65  ular must not be
35ba0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35bb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
35bc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
35bd0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
35be0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
35bf0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
35c00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35c10 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
35c20 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
35c30 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
35c40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35c50 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
35c60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
35c70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
35c80 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
35c90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
35ca0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
35cb0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
35cc0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
35cd0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
35ce0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
35cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
35d00 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
35d10 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
35d20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
35d30 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
35d40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
35d50 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
35d60 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
35d70 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
35d80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
35d90 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
35da0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
35db0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
35dc0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
35dd0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35de0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35df0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
35e00 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
35e10 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
35e20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35e30 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
35e40 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
35e50 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
35e60 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
35e70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
35e80 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
35e90 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
35ea0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
35eb0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
35ec0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
35ed0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
35ee0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
35ef0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
35f00 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
35f10 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
35f20 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
35f30 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
35f40 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
35f50 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
35f60 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
35f70 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
35f80 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
35f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35fa0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
35fb0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
35fc0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
35fd0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
35fe0 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20 61  .** The commit a
35ff0 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  nd rollback hook
36000 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20 6e   callbacks are n
36010 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a 2a  ot reentrant..**
36020 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
36030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
36040 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
36050 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
36060 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
36070 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
36080 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
36090 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
360a0 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
360b0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
360c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
360d0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
360e0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
360f0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
36100 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
36110 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
36120 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
36130 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
36140 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
36150 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
36160 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61 6e   that running an
36170 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61 74  y other SQL stat
36180 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  ements, includin
36190 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  g SELECT stateme
361a0 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65 6c  nts,.** or merel
361b0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
361c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
361d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
361e0 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69 66  ep()] will modif
361f0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
36200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
36210 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
36220 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
36230 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
36240 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20  ** ^Registering 
36250 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20  a NULL function 
36260 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c  disables the cal
36270 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  lback..**.** ^Wh
36280 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  en the commit ho
36290 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  ok callback rout
362a0 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ine returns zero
362b0 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a  , the [COMMIT].*
362c0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  * operation is a
362d0 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e  llowed to contin
362e0 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49  ue normally.  ^I
362f0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
36300 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
36310 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
36320 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
36330 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
36340 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65  LLBACK]..** ^The
36350 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69   rollback hook i
36360 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72  s invoked on a r
36370 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73  ollback that res
36380 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d  ults from a comm
36390 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72  it.** hook retur
363a0 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a  ning non-zero, j
363b0 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20  ust as it would 
363c0 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65  be with any othe
363d0 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  r rollback..**.*
363e0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
363f0 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c  ses of this API,
36400 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
36410 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20 62  s said to have b
36420 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61  een.** rolled ba
36430 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69  ck if an explici
36440 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61  t "ROLLBACK" sta
36450 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74  tement is execut
36460 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72  ed, or.** an err
36470 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74  or or constraint
36480 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69   causes an impli
36490 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20  cit rollback to 
364a0 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72  occur..** ^The r
364b0 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b  ollback callback
364c0 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20   is not invoked 
364d0 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  if a transaction
364e0 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63   is.** automatic
364f0 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
36500 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61 74   because the dat
36510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36520 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
36530 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
36540 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36550 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
36560 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36570 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
36580 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
36590 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
365a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
365b0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
365c0 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
365d0 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
365e0 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
365f0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
36600 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
36610 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
36620 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
36630 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
36640 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  te_hook() interf
36650 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
36660 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
36670 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  n.** with the [d
36680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36690 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20 62  on] identified b
366a0 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  y the first argu
366b0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  ment.** to be in
366c0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
366d0 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c   row is updated,
366e0 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
366f0 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  eted..** ^Any ca
36700 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
36710 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
36720 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
36730 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
36740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36750 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
36760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
36770 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
36780 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
36790 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76   function to inv
367a0 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f  oke when a.** ro
367b0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
367c0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
367d0 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  d..** ^The first
367e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
367f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
36800 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
36810 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
36820 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
36830 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73  ook()..** ^The s
36840 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61  econd callback a
36850 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
36860 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  f [SQLITE_INSERT
36870 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  ], [SQLITE_DELET
36880 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
36890 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70 65 6e  E_UPDATE], depen
368a0 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70 65 72  ding on the oper
368b0 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75 73 65  ation that cause
368c0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  d the callback.*
368d0 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e  * to be invoked.
368e0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
368f0 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  nd fourth argume
36900 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  nts to the callb
36910 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e  ack contain poin
36920 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  ters to the.** d
36930 61 74 61 62 61 73 65 20 61 6e 64 20 74 61 62 6c  atabase and tabl
36940 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e  e name containin
36950 67 20 74 68 65 20 61 66 66 65 63 74 65 64 20 72  g the affected r
36960 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61  ow..** ^The fina
36970 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d  l callback param
36980 65 74 65 72 20 69 73 20 74 68 65 20 5b 72 6f 77  eter is the [row
36990 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a  id] of the row..
369a0 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73 65 20  ** ^In the case 
369b0 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20 74 68  of an update, th
369c0 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64  is is the [rowid
369d0 5d 20 61 66 74 65 72 20 74 68 65 20 75 70 64 61  ] after the upda
369e0 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a  te takes place..
369f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70 64 61  **.** ^(The upda
36a00 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69  te hook is not i
36a10 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e 74 65  nvoked when inte
36a20 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61 62 6c  rnal system tabl
36a30 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69  es are.** modifi
36a40 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f  ed (i.e. sqlite_
36a50 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c 69 74  master and sqlit
36a60 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a  e_sequence).)^.*
36a70 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 75 72  *.** ^In the cur
36a80 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
36a90 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20  ion, the update 
36aa0 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69  hook.** is not i
36ab0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c  nvoked when dupl
36ac0 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65  ication rows are
36ad0 20 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65   deleted because
36ae0 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f   of an.** [ON CO
36af0 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46  NFLICT | ON CONF
36b00 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c  LICT REPLACE] cl
36b10 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74  ause.  ^Nor is t
36b20 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
36b30 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72  * invoked when r
36b40 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
36b50 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63  using the [trunc
36b60 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
36b70 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74  ]..** The except
36b80 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20  ions defined in 
36b90 74 68 69 73 20 70 61 72 61 67 72 61 70 68 20 6d  this paragraph m
36ba0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61  ight change in a
36bb0 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
36bc0 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
36bd0 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65 20 68  .** The update h
36be0 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ook implementati
36bf0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
36c00 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
36c10 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
36c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36c30 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
36c40 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
36c50 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
36c60 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
36c70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36c80 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
36c90 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
36ca0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
36cb0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
36cc0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
36cd0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
36ce0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a  he update hook..
36cf0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
36d00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
36d10 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36d20 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
36d30 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
36d40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36d50 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
36d60 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
36d70 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
36d80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36d90 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
36da0 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e  (D,C,P) function
36db0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
36dc0 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20  P argument from 
36dd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
36de0 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  l.** on the same
36df0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36e00 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
36e10 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
36e20 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a  st call on D..**
36e30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
36e40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74   [sqlite3_commit
36e50 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71  _hook()] and [sq
36e60 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
36e70 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ook()].** interf
36e80 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  aces..*/.SQLITE_
36e90 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
36ea0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
36eb0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36ec0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
36ed0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
36ee0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
36ef0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
36f00 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
36f10 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
36f20 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
36f30 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
36f40 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
36f50 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
36f60 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
36f70 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
36f80 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
36f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
36fa0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
36fb0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
36fc0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
36fd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
36fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
36ff0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
37000 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
37010 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
37020 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
37030 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
37040 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37050 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
37060 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
37070 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
37080 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
37090 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
370a0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
370b0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
370c0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
370d0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
370e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
370f0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
37100 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
37110 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
37120 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
37130 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
37140 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
37150 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
37160 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
37170 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
37180 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
37190 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
371a0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
371b0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
371c0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
371d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
371e0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
371f0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
37200 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
37210 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
37220 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
37230 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
37240 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
37250 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
37260 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
37270 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
37280 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
37290 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
372a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
372b0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
372c0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
372d0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
372e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
372f0 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
37300 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
37310 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
37320 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
37330 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
37340 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
37350 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
37360 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
37370 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
37380 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
37390 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
373a0 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ode].*/.SQLITE_A
373b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
373c0 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63  nable_shared_cac
373d0 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  he(int);../*.** 
373e0 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70  CAPI3REF: Attemp
373f0 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d  t To Free Heap M
37400 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  emory.**.** ^The
37410 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
37420 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66  _memory() interf
37430 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
37440 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20  free N bytes.** 
37450 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62  of heap memory b
37460 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e  y deallocating n
37470 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
37480 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a  ory allocations.
37490 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64  ** held by the d
374a0 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e  atabase library.
374b0 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74     Memory used t
374c0 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65  o cache database
374d0 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70  .** pages to imp
374e0 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  rove performance
374f0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
37500 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20  f non-essential 
37510 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69  memory..** ^sqli
37520 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37530 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65  ry() returns the
37540 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
37550 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
37560 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20  .** which might 
37570 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20  be more or less 
37580 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
37590 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54  requested..** ^T
375a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
375b0 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74  se_memory() rout
375c0 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72  ine is a no-op r
375d0 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a  eturning zero.**
375e0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e 6f   if SQLite is no
375f0 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  t compiled with 
37600 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
37610 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
37620 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
37630 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 72  o: [sqlite3_db_r
37640 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
37650 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
37660 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  nt sqlite3_relea
37670 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a  se_memory(int);.
37680 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37690 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55 73 65   Free Memory Use
376a0 64 20 42 79 20 41 20 44 61 74 61 62 61 73 65 20  d By A Database 
376b0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
376c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
376d0 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
376e0 44 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  D) interface att
376f0 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20 61 73  empts to free as
37700 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20 6d 65   much heap.** me
37710 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62 6c 65  mory as possible
37720 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 63   from database c
37730 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55 6e 6c  onnection D. Unl
37740 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ike the.** [sqli
37750 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
37760 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  ry()] interface,
37770 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
37780 69 73 20 65 66 66 65 63 74 20 65 76 65 6e 0a 2a  is effect even.*
37790 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53 51 4c  * when then [SQL
377a0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
377b0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20 63 6f  Y_MANAGEMENT] co
377c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
377d0 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65 64 2e  n is.** omitted.
377e0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
377f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   [sqlite3_releas
37800 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f 0a 53  e_memory()].*/.S
37810 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
37820 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65  lite3_db_release
37830 5f 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a  _memory(sqlite3*
37840 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37850 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
37860 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
37870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37880 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
37890 69 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  it64() interface
378a0 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65   sets and/or que
378b0 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ries the.** soft
378c0 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d   limit on the am
378d0 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d  ount of heap mem
378e0 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20  ory that may be 
378f0 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
37900 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ite..** ^SQLite 
37910 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20  strives to keep 
37920 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c  heap memory util
37930 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68  ization below th
37940 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c  e soft heap.** l
37950 69 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67  imit by reducing
37960 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
37970 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65  ages held in the
37980 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61   page cache.** a
37990 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73  s heap memory us
379a0 61 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20  ages approaches 
379b0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  the limit..** ^T
379c0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
379d0 69 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63  it is "soft" bec
379e0 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68  ause even though
379f0 20 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20   SQLite strives 
37a00 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77  to stay.** below
37a10 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77   the limit, it w
37a20 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c  ill exceed the l
37a30 69 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e  imit rather than
37a40 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20   generate.** an 
37a50 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65  [SQLITE_NOMEM] e
37a60 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  rror.  In other 
37a70 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20  words, the soft 
37a80 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69  heap limit .** i
37a90 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
37aa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
37ab0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
37ac0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
37ad0 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65  limit64() is the
37ae0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20   size of.** the 
37af0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37b00 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c  prior to the cal
37b10 6c 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69  l, or negative i
37b20 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
37b30 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20  .** error.  ^If 
37b40 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
37b50 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68  s negative.** th
37b60 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20  en no change is 
37b70 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74  made to the soft
37b80 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65   heap limit.  He
37b90 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74  nce, the current
37ba0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20  .** size of the 
37bb0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37bc0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
37bd0 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  d by invoking.**
37be0 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
37bf0 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74  ap_limit64() wit
37c00 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67  h a negative arg
37c10 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ument..**.** ^If
37c20 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
37c30 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  is zero then the
37c40 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
37c50 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
37c60 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68  .** ^(The soft h
37c70 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  eap limit is not
37c80 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65   enforced in the
37c90 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
37ca0 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e  ntation.** if on
37cb0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c  e or more of fol
37cc0 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e  lowing condition
37cd0 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a  s are true:.**.*
37ce0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
37cf0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37d00 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72  it is set to zer
37d10 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72  o..** <li> Memor
37d20 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20  y accounting is 
37d30 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
37d40 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
37d50 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  the.**      [sql
37d60 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
37d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
37d80 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72  TATUS],...) star
37d90 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e  t-time option an
37da0 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53  d.**      the [S
37db0 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
37dc0 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65  MSTATUS] compile
37dd0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
37de0 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61   <li> An alterna
37df0 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20  tive page cache 
37e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37e10 73 20 73 70 65 63 69 66 69 65 64 20 75 73 69 6e  s specified usin
37e20 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
37e30 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
37e40 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
37e50 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e  2],...)..** <li>
37e60 20 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20   The page cache 
37e70 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69  allocates from i
37e80 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f  ts own memory po
37e90 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20  ol supplied.**  
37ea0 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f      by [sqlite3_
37eb0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
37ec0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
37ed0 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68  ],...) rather th
37ee0 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20  an.**      from 
37ef0 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75  the heap..** </u
37f00 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e  l>)^.**.** Begin
37f10 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
37f20 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20   version 3.7.3, 
37f30 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
37f40 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a  mit is enforced.
37f50 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
37f60 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
37f70 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
37f80 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
37f90 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  MENT].** compile
37fa0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
37fb0 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b  invoked.  With [
37fc0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
37fd0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
37fe0 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  ,.** the soft he
37ff0 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f  ap limit is enfo
38000 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65  rced on every me
38010 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  mory allocation.
38020 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51    Without.** [SQ
38030 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
38040 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20  RY_MANAGEMENT], 
38050 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
38060 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f  mit is only enfo
38070 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d  rced.** when mem
38080 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64  ory is allocated
38090 20 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63   by the page cac
380a0 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67  he.  Testing sug
380b0 67 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75  gests that becau
380c0 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63  se.** the page c
380d0 61 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64  ache is the pred
380e0 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75  ominate memory u
380f0 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d  ser in SQLite, m
38100 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
38110 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65  ons will achieve
38120 20 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68   adequate soft h
38130 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63  eap limit enforc
38140 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a  ement without.**
38150 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c   the use of [SQL
38160 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
38170 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a  Y_MANAGEMENT]..*
38180 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73  *.** The circums
38190 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69  tances under whi
381a0 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  ch SQLite will e
381b0 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20  nforce the soft 
381c0 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a  heap limit may.*
381d0 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74  * changes in fut
381e0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
381f0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
38200 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
38210 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  t64 sqlite3_soft
38220 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73 71  _heap_limit64(sq
38230 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b 0a  lite3_int64 N);.
38240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38250 20 44 65 70 72 65 63 61 74 65 64 20 53 6f 66 74   Deprecated Soft
38260 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74 65   Heap Limit Inte
38270 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43 41  rface.** DEPRECA
38280 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  TED.**.** This i
38290 73 20 61 20 64 65 70 72 65 63 61 74 65 64 20 76  s a deprecated v
382a0 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  ersion of the [s
382b0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
382c0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 69  _limit64()].** i
382d0 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69 73 20  nterface.  This 
382e0 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76 69  routine is provi
382f0 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
38300 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  al compatibility
38310 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6e  .** only.  All n
38320 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
38330 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a 2a  should use the.*
38340 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  * [sqlite3_soft_
38350 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20  heap_limit64()] 
38360 69 6e 74 65 72 66 61 63 65 20 72 61 74 68 65 72  interface rather
38370 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e 0a   than this one..
38380 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
38390 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
383a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 6f 66  void sqlite3_sof
383b0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74  t_heap_limit(int
383c0 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   N);.../*.** CAP
383d0 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
383e0 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
383f0 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
38400 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
38410 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
38420 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
38430 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
38440 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
38450 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
38460 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
38470 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38480 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
38490 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
384a0 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
384b0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
384c0 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
384d0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
384e0 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
384f0 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
38500 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
38510 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
38520 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
38530 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
38540 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
38550 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
38560 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
38570 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
38580 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
38590 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
385a0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
385b0 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
385c0 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
385d0 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
385e0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
385f0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
38600 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
38610 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
38620 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
38630 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
38640 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
38650 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
38660 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
38670 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
38680 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
38690 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
386a0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
386b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
386c0 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
386d0 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
386e0 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
386f0 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
38700 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
38710 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
38720 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
38730 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
38740 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
38750 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
38760 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
38770 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
38780 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
38790 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
387a0 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
387b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
387c0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
387d0 6