System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 590b798ebeefd725196378752668006913a47095:


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 2e 31 22 0a 23 64 65 66 69 6e 65  .7.12.1".#define
1030: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1040: 4e 55 4d 42 45 52 20 33 30 30 37 30 31 32 0a 23  NUMBER 3007012.#
1050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
1060: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
1070: 31 32 2d 30 35 2d 32 32 20 30 32 3a 34 35 3a 35  12-05-22 02:45:5
1080: 33 20 36 64 33 32 36 64 34 34 66 64 31 64 36 32  3 6d326d44fd1d62
1090: 36 61 61 65 30 65 38 34 35 36 65 35 66 61 32 30  6aae0e8456e5fa20
10a0: 34 39 66 31 63 65 30 37 38 39 22 0a 0a 2f 2a 0a  49f1ce0789"../*.
10b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
10c0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
10d0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
10e0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
10f0: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1100: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1110: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1120: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1130: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1140: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1150: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1160: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1170: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1180: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1190: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
11a0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
11b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
11c0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
11d0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
11e0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
11f0: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1200: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1210: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1220: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1230: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1240: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1250: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1260: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1270: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1280: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1290: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
12a0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
12b0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
12c0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
12d0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
12e0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
12f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1300: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1310: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1320: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1330: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1340: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1350: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1360: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1370: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1380: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1390: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
13b0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
13c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13d0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
13e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
13f0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1400: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1410: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1420: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1430: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1440: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1450: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1460: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1470: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1480: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1490: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
14a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
14c0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
14d0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
14e0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
14f0: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1500: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1510: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1520: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1530: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1540: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1550: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1560: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1570: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1580: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
1590: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
15a0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
15b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
15c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
15d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
15e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
15f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1600: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1610: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1620: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1630: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1640: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1650: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1660: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1670: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1680: 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
1690: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
16a0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
16b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16c0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
16d0: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
16e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
16f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1700: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1710: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1720: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1730: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1740: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1750: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1760: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
1770: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1780: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1790: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
17a0: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
17b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
17c0: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
17d0: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
17e0: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
17f0: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1800: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1810: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
1820: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
1830: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
1840: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
1850: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
1860: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1870: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1880: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1890: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
18a0: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
18b0: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
18c0: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
18d0: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
18e0: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
18f0: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1900: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1910: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
1920: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
1930: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
1940: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
1950: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1960: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
1970: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1980: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1990: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
19a0: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
19b0: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
19c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
19d0: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
19e0: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
19f0: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1a00: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1a10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1a20: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
1a30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a40: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
1a50: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
1a60: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
1a70: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a80: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a90: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1aa0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1ab0: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1ac0: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1ae0: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1af0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1b00: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1b10: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1b20: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1b30: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1b40: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b50: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  AGS.SQLITE_API i
1b60: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1b70: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1b80: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1b90: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
1ba0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1bc0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1be0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1bf0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1c00: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1c10: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c20: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1c30: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c40: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1c50: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1c60: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1c70: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1c80: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1c90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1ca0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1cb0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1cc0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1cd0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1ce0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1cf0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1d00: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1d10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d20: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1d30: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1d40: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1d50: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1d60: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1d70: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1d80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1d90: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1da0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1db0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1dc0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1dd0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1de0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1df0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1e00: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1e10: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1e20: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1e30: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1e40: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1e50: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1e60: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1e70: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1e80: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1e90: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1ea0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1eb0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1ec0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1ed0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1ee0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1ef0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1f00: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1f10: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1f20: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f30: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
1f40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
1f50: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1f60: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1f70: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1f80: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1f90: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1fa0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1fb0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1fc0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1fd0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1fe0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1ff0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
2000: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2010: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2020: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2030: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2040: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2050: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2060: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2070: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2080: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2090: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
20a0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
20b0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
20c0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
20d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
20e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
20f0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
2100: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2110: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2130: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2140: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2150: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
2160: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2170: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
2180: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
2190: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
21a0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
21b0: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
21c0: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
21d0: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
21e0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
21f0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
2200: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
2210: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
2220: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
2230: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2240: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
2250: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
2260: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
2270: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
2280: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
2290: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
22a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
22b0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22c0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
22d0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22e0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
22f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
2300: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2310: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2320: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2330: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2340: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2350: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2360: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2370: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2380: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2390: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
23a0: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
23b0: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
23c0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
23d0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
23e0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
23f0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
2400: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
2410: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2420: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2430: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2450: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2460: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2470: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2480: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69  e3_close()].** i
2490: 73 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  s its destructor
24a0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e  .  There are man
24b0: 79 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63  y other interfac
24c0: 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b  es (such as.** [
24d0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
24e0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
24f0: 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2500: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2510: 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
2520: 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20  ()] to name but 
2530: 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20  three) that are 
2540: 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a  methods on an.**
2550: 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e   sqlite3 object.
2560: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2570: 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74  ct sqlite3 sqlit
2580: 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e3;../*.** CAPI3
2590: 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65  REF: 64-Bit Inte
25a0: 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59  ger Types.** KEY
25b0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e  WORDS: sqlite_in
25c0: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  t64 sqlite_uint6
25d0: 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20  4.**.** Because 
25e0: 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73  there is no cros
25f0: 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74  s-platform way t
2600: 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74  o specify 64-bit
2610: 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a   integer types.*
2620: 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65  * SQLite include
2630: 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36  s typedefs for 6
2640: 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64  4-bit signed and
2650: 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
2660: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  rs..**.** The sq
2670: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2680: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2690: 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
26a0: 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e   type definition
26b0: 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  s..** The sqlite
26c0: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26d0: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61  e_uint64 types a
26e0: 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72  re supported for
26f0: 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f   backwards.** co
2700: 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79  mpatibility only
2710: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2720: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2730: 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65  qlite_int64 type
2740: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65  s can store inte
2750: 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  ger values.** be
2760: 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33  tween -922337203
2770: 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b  6854775808 and +
2780: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
2790: 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20  807 inclusive.  
27a0: 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ^The.** sqlite3_
27b0: 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  uint64 and sqlit
27c0: 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63  e_uint64 types c
27d0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
27e0: 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77   values .** betw
27f0: 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36  een 0 and +18446
2800: 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20  744073709551615 
2810: 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69  inclusive..*/.#i
2820: 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  fdef SQLITE_INT6
2830: 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66  4_TYPE.  typedef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  PE sqlite_int64;
2860: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2870: 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  ned SQLITE_INT64
2880: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e  _TYPE sqlite_uin
2890: 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e  t64;.#elif defin
28a0: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20  ed(_MSC_VER) || 
28b0: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e  defined(__BORLAN
28c0: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20  DC__).  typedef 
28d0: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69  __int64 sqlite_i
28e0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28f0: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34  unsigned __int64
2900: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2910: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20  #else.  typedef 
2920: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71  long long int sq
2930: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2940: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c  pedef unsigned l
2950: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2960: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64  ite_uint64;.#end
2970: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  if.typedef sqlit
2980: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  e_int64 sqlite3_
2990: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73  int64;.typedef s
29a0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c  qlite_uint64 sql
29b0: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a  ite3_uint64;../*
29c0: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67  .** If compiling
29d0: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72   for a processor
29e0: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61   that lacks floa
29f0: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f  ting point suppo
2a00: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74  rt,.** substitut
2a10: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c  e integer for fl
2a20: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f  oating-point..*/
2a30: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f  .#ifdef SQLITE_O
2a40: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49  MIT_FLOATING_POI
2a50: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62  NT.# define doub
2a60: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  le sqlite3_int64
2a70: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2a80: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67  API3REF: Closing
2a90: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e   A Database Conn
2aa0: 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
2ab0: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2ac0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65  ) routine is the
2ad0: 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20  ject..** ^Calls 
2b00: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  to sqlite3_close
2b10: 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
2b20: 5f 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69  _OK if the [sqli
2b30: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a  te3] object is.*
2b40: 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64  * successfully d
2b50: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2b60: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2b70: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b80: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2b90: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2ba0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bb0: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2bc0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bd0: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
2be0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2bf0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2c00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
2c10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
2c20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2c30: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2c40: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2c50: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2c60: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2c70: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2c80: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2c90: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2ca0: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2cb0: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2cc0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2cd0: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
2ce0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
2cf0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
2d00: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
2d10: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
2d20: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
2d30: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2d40: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2d50: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2d60: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2d70: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2d80: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2d90: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2da0: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2db0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2dc0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2dd0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
2de0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
2df0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
2e00: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2e10: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
2e20: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2e30: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2e40: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2e50: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2e60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2e70: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2e80: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2e90: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2ea0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
2eb0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
2ec0: 73 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a  se(sqlite3 *);..
2ed0: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
2ee0: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
2ef0: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
2f00: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
2f10: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
2f20: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
2f30: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
2f40: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
2f50: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
2f60: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
2f70: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
2f80: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
2f90: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
2fa0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2fb0: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
2fc0: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
2fd0: 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ce.**.** The sql
2fe0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
2ff0: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3000: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
3010: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
3020: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
3030: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
3040: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
3050: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
3060: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3070: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3080: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3090: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
30a0: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
30b0: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
30c0: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
30d0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
30e0: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
30f0: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3100: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
3110: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
3120: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
3130: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
3140: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
3150: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
3160: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3170: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3180: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3190: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
31a0: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
31b0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
31c0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
31d0: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
31e0: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
31f0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3200: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
3210: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
3220: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
3230: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
3240: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
3250: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
3260: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3270: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3280: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3290: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
32a0: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
32b0: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
32c0: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
32d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
32e0: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
32f0: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3300: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
3310: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
3320: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
3330: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
3340: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
3350: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
3360: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3370: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3380: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3390: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
33a0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
33b0: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
33c0: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
33d0: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
33e0: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
33f0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3400: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3410: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
3420: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
3430: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
3440: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
3450: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3460: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3470: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3480: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3490: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
34a0: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
34b0: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
34c0: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
34d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
34e0: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
34f0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3500: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3510: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3520: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3540: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3550: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3560: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3570: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3580: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
35b0: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
35c0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
35d0: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
35e0: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
35f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3600: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3610: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3620: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3630: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3640: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3650: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3660: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3670: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3680: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3690: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
36a0: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
36b0: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
36c0: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
36d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
36e0: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
36f0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3700: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3710: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3720: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3730: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3740: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3750: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3760: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3770: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3780: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3790: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
37a0: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
37b0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
37c0: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
37d0: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
37e0: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
37f0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3800: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3810: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3820: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3830: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3840: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3850: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3860: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3870: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3880: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3890: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
38a0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
38b0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
38c0: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
38d0: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
38e0: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
38f0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3900: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3910: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3920: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3930: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3940: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3950: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3960: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3970: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3980: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3990: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
39a0: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
39b0: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
39c0: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
39d0: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
39e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
39f0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3a00: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3a10: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3a20: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3a30: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3a40: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3a50: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e  lication must in
3a60: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3a70: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3a80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3a90: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3aa0: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3ab0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3ac0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ad0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3ae0: 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62 61 73  t close [databas
3af0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
3b00: 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
3b10: 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d     the 1st param
3b20: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3b30: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3b40: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3b50: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20  unning..** <li> 
3b60: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
3b70: 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20  must not modify 
3b80: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
3b90: 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e  t text passed in
3ba0: 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32  to.**      the 2
3bb0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
3bc0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3bd0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3be0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3bf0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ul>.*/.SQLI
3c00: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3c10: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
3c20: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
3c50: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
3c60: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst 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 20 20 2f 2a 20 53 51 4c            /* SQL
3c90: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
3ca0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
3cb0: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
3cc0: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
3cd0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
3ce0: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
3cf0: 2a 2c 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 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
3d20: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
3d30: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
3d40: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d60: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
3d70: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
3d80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
3d90: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
3da0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
3db0: 49 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f  ITE_OK {error co
3dc0: 64 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73  de} {error codes
3dd0: 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
3de0: 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65  result code} {re
3df0: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
3e00: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
3e10: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
3e20: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
3e30: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
3e40: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
3e50: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
3e60: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
3e70: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
3e80: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
3e90: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
3ea0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
3eb0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
3ec0: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
3ed0: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20  TE_IOERR_READ | 
3ee0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
3ef0: 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  codes],.** [sqli
3f00: 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
3f10: 6c 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f  lict()] [SQLITE_
3f20: 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c  ROLLBACK | resul
3f30: 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65  t codes]..*/.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20  fine SQLITE_OK  
3f50: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
3f60: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c  Successful resul
3f70: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e  t */./* beginnin
3f80: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  g-of-error-codes
3f90: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fa0: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20  TE_ERROR        
3fb0: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72  1   /* SQL error
3fc0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
3fd0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
3fe0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20  SQLITE_INTERNAL 
3ff0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72      2   /* Inter
4000: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20  nal logic error 
4010: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65  in SQLite */.#de
4020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d  fine SQLITE_PERM
4030: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20           3   /* 
4040: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f  Access permissio
4050: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4060: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
4070: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43          4   /* C
4080: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
4090: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f  requested an abo
40a0: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  rt */.#define SQ
40b0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20  LITE_BUSY       
40c0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74    5   /* The dat
40d0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f  abase file is lo
40e0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
40f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20  SQLITE_LOCKED   
4100: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62      6   /* A tab
4110: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  le in the databa
4120: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  se is locked */.
4130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4140: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20  OMEM        7   
4150: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61  /* A malloc() fa
4160: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  iled */.#define 
4170: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
4180: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d      8   /* Attem
4190: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65  pt to write a re
41a0: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20  adonly database 
41b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41c0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39  E_INTERRUPT    9
41d0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
41e0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71  terminated by sq
41f0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
4200: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )*/.#define SQLI
4210: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31  TE_IOERR       1
4220: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64  0   /* Some kind
4230: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72   of disk I/O err
4240: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23  or occurred */.#
4250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
4260: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f  RRUPT     11   /
4270: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64  * The database d
4280: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c  isk image is mal
4290: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e  formed */.#defin
42a0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  e SQLITE_NOTFOUN
42b0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b  D    12   /* Unk
42c0: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73  nown opcode in s
42d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
42e0: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  rol() */.#define
42f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4300: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4310: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4320: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4330: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4340: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4350: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4360: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4370: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4390: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
43a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
43b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
43c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
43e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
43f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4410: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4420: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4430: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4440: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4450: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4460: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4470: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4480: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4490: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
44a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
44b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
44c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
44e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
44f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4500: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4510: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4520: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4530: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4540: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4550: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4560: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4570: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4580: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4590: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
45b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
45c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
45d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
45e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
45f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4600: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4610: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4620: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4630: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4640: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4650: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4660: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4670: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4680: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4690: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
46a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
46b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
46d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
46e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
46f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4700: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4710: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4720: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4730: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4740: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4750: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4760: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4770: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4780: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4790: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
47a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
47b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
47c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
47d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
47e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
47f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4800: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4810: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4820: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4830: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4840: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4850: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4860: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4870: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4880: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4890: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
48a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
48b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
48c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
48d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
48e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
48f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4900: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4910: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4920: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4930: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4940: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4950: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4960: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4970: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4980: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4990: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
49a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
49b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
49c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
49d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
49e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4a00: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4a10: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4a20: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4a30: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4a40: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4a50: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4a60: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4a70: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4a80: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4a90: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4aa0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4ab0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4ac0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4ad0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4ae0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4af0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4b00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4b10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4b20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4b30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4b40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4b50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4b60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4b70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4b80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4b90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4ba0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4bb0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4bc0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4be0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4c10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4c30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4c50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4c60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4c70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4c80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4c90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ca0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4cb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4cc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4cd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ce0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4cf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4d10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4d20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4d30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4d40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4d50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4d60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4d70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4d80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4d90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4da0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4db0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4dd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4de0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4df0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4e20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4ee0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4f20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4fe0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ff0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
5000: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5010: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
5020: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5030: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
5040: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5050: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
5060: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5070: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
5080: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5090: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
50a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
50b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
50c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50d0: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20  TE_IOERR_SHMMAP 
50e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
50f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c  TE_IOERR | (21<<
5100: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5110: 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20  TE_IOERR_SEEK   
5120: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5130: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c  TE_IOERR | (22<<
5140: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5150: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
5160: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
5170: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
51a0: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
51b0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
51c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51d0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
51e0: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
51f0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5200: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5210: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5220: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
5230: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5240: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5250: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
5260: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5270: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5280: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5290: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
52a0: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
52b0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
52c0: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
52d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
52e0: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
52f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5300: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5320: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
5340: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f  ORT | (2<<8))../
5350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5360: 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70  lags For File Op
5370: 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  en Operations.**
5380: 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61  .** These bit va
5390: 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lues are intende
53a0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65  d for use in the
53b0: 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65  .** 3rd paramete
53c0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
53d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
53e0: 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e  erface and.** in
53f0: 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
5400: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
5410: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
5420: 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  thod..*/.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5440: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
5450: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
5460: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5470: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5480: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5490: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
54a0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
54b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
54c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
54d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
54e0: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
54f0: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5500: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5510: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5520: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5530: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5540: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
5550: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5560: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
5570: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
5580: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
5590: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
55a0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
55b0: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
55c0: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
55d0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
55e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5600: 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20  00000040  /* Ok 
5610: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5620: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5640: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5650: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5660: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5670: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5680: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5690: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
56a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
56b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
56c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
56d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
56e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
56f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5700: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5710: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5720: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5730: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5740: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5750: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5760: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5770: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5780: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5790: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
57a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
57b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
57c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
57d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
57e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
57f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5800: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5810: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5820: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5830: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5840: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5850: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5860: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5870: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5880: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5890: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
58a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
58b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
58c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
58d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
58e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
58f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5900: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5910: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5920: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5930: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
5940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5950: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
5960: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
5970: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5990: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
59a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
59b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
59c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
59d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
59e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
59f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5a00: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5a10: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
5a20: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
5a30: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
5a40: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5a50: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5a60: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5a70: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5a80: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5a90: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5aa0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5ab0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5ac0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5ad0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5ae0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
5af0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5b00: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5b10: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
5b20: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5b30: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b40: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5b50: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5b60: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5b70: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5b80: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5b90: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5ba0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5bb0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5bc0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5bd0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5be0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5bf0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5c00: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5c10: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
5c20: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
5c30: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
5c40: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5c50: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5c60: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5c70: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5c80: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5c90: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5ca0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5cb0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5cc0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5cd0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5ce0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5cf0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5d00: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
5d10: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
5d20: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
5d30: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
5d40: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
5d50: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
5d60: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
5d70: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
5d80: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
5d90: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
5da0: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
5db0: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
5dc0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
5dd0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
5de0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
5df0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
5e00: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
5e10: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
5e20: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
5e30: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5e50: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
5e60: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e80: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
5e90: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5ea0: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5eb0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5ec0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5ed0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
5ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5ef0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5f00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f10: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
5f20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
5f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5f40: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5f50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5f60: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
5f70: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5f80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f90: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5fa0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fb0: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5fc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5fd0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
5fe0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6000: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
6010: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6020: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
6030: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6040: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
6050: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
6060: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6070: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
6080: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
6090: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
60a0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
60b0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
60c0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
60d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
60e0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
60f0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
6100: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6110: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6120: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6130: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6140: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6150: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6160: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6170: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6180: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6190: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
61a0: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
61b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
61c0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
61e0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
61f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6200: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6210: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6220: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6230: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6240: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6250: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6270: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6280: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6290: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
62a0: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
62b0: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
62c0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
62d0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
62e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
62f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6300: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6310: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6320: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6330: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6340: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6350: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6360: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6370: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6380: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6390: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
63a0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
63b0: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
63c0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
63d0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
63e0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
63f0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6400: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6410: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6420: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6430: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6440: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6450: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6460: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
6470: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
6480: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6490: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
64a0: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
64b0: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
64c0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
64d0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
64e0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
64f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6500: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6510: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
6520: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
6530: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
6540: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
6550: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
6560: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
6570: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
6580: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
6590: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
65a0: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
65b0: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
65c0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
65d0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
65e0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
65f0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
6600: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
6610: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
6620: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
6630: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
6640: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
6650: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
6660: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
6670: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
6680: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
6690: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
66a0: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
66b0: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
66c0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
66d0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
66e0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
66f0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
6700: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6710: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6720: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
6730: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
6740: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
6750: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
6760: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
6770: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
6780: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
6790: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
67a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
67b0: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
67c0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
67d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
67e0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
67f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
6800: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
6810: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
6820: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6830: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
6840: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
6850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6860: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
6870: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
6880: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
6890: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
68a0: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
68b0: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
68c0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
68d0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
68e0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
68f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
6900: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
6910: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
6920: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
6930: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
6940: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
6950: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
6960: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6970: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
6980: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
6990: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
69a0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
69b0: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
69c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
69d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
69e0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
69f0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
6a00: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
6a10: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
6a20: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
6a30: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
6a40: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
6a50: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
6a60: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
6a70: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
6a80: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
6a90: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
6aa0: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
6ab0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6ac0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
6ad0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
6ae0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
6af0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
6b00: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
6b10: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
6b20: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
6b30: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
6b40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
6b50: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
6b60: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
6b70: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
6b80: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
6b90: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
6ba0: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
6bb0: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
6bc0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
6bd0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
6be0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
6bf0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6c00: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
6c10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
6c20: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
6c30: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
6c40: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
6c50: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
6c60: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
6c70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
6c80: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
6c90: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
6ca0: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
6cb0: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
6cc0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
6cd0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
6ce0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
6cf0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
6d00: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
6d10: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
6d20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6d30: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
6d40: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
6d50: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
6d60: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
6d70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
6d80: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
6d90: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
6da0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6db0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
6dc0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
6dd0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
6de0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
6df0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
6e00: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
6e10: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e20: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
6e30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6e40: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
6e50: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
6e60: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
6e70: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
6e80: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
6e90: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
6ea0: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
6eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
6ec0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
6ed0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6ee0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
6ef0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
6f00: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
6f10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6f20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
6f30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6f40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
6f50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6f60: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
6f70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6f80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6f90: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
6fa0: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
6fb0: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
6fc0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
6fd0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
6fe0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
6ff0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7000: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7010: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7020: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7030: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7040: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7050: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7060: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7070: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7080: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7090: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
70a0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
70b0: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
70c0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
70d0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
70e0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
70f0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7100: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7110: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7120: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7130: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7140: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7150: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7160: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7170: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7180: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7190: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
71a0: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
71b0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
71c0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
71d0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
71e0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
71f0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7200: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7210: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7220: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7230: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7240: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7250: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7260: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7270: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7280: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7290: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
72a0: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
72b0: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
72c0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
72d0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
72e0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
72f0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7300: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7310: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7320: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7330: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7340: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7350: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7360: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7370: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7380: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
7390: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
73a0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
73b0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
73c0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
73d0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
73e0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
73f0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7400: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7410: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7420: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7430: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7440: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7450: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7460: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7470: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7480: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7490: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
74a0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
74b0: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
74c0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
74d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
74e0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
74f0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7500: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7510: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7520: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7530: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7540: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7550: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7560: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
7570: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
7580: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
7590: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
75a0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
75b0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
75c0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
75d0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
75e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
75f0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
7600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7610: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
7620: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7630: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
7640: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7650: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
7660: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7670: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
7680: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7690: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
76a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
76b0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
76c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
76d0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
76e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
76f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
7700: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7710: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
7720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7730: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7740: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
7750: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7760: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
7770: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
7780: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
7790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
77a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
77b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
77c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
77d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
77e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
77f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
7800: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
7810: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
7820: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
7830: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
7840: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
7850: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
7860: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
7870: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
7880: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7890: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
78a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
78b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
78c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
78d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
78e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
78f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
7900: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
7910: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
7920: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
7930: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7940: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
7950: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
7960: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
7970: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
7980: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
7990: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
79a0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
79b0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
79c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
79d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
79e0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
79f0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
7a00: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
7a10: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
7a20: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
7a30: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
7a40: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7a50: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
7a60: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
7a70: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
7a80: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
7a90: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
7aa0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
7ab0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
7ac0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
7ad0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
7ae0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
7af0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
7b00: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7b10: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
7b20: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
7b30: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
7b40: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
7b50: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
7b60: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
7b70: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
7b80: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
7b90: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
7ba0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
7bb0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
7bc0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7bd0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7be0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
7bf0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7c00: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
7c10: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
7c20: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7c30: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
7c40: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
7c50: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
7c60: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
7c70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
7c80: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7c90: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
7ca0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
7cb0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
7cc0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
7cd0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
7ce0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
7cf0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
7d00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
7d10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7d20: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
7d30: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
7d40: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7d50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
7d60: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7d70: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
7d80: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
7d90: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7da0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
7db0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
7dc0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
7dd0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
7de0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
7df0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
7e00: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
7e10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7e20: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
7e30: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
7e40: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
7e50: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
7e60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
7e70: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
7e80: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
7e90: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
7ea0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
7eb0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
7ec0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  2 */.  /* Additi
7ed0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
7ee0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
7ef0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
7f00: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7f10: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
7f20: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
7f30: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
7f40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7f50: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7f60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7f70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7f80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7f90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7fa0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7fb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7fc0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7fe0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7ff0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
8000: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
8010: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
8020: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
8030: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8040: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
8050: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
8060: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
8070: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
8080: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
8090: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
80a0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
80b0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
80c0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
80d0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
80e0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
80f0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
8100: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
8110: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
8120: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
8130: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
8140: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
8150: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
8160: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
8170: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
8180: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
8190: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
81a0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
81b0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
81c0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
81d0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
81e0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
81f0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
8200: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
8210: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
8220: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
8230: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
8240: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
8250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
8260: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
8270: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
8280: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
8290: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
82a0: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
82b0: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
82c0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
82d0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
82e0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
82f0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
8300: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
8310: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
8320: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
8330: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
8340: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8350: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
8360: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8370: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
8380: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8390: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
83a0: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
83b0: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
83c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
83d0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
83e0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
83f0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
8400: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
8410: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
8420: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8430: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
8440: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
8450: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
8460: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
8470: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
8480: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
8490: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
84a0: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
84b0: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
84c0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
84d0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
84e0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
84f0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
8500: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
8510: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
8520: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
8530: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
8540: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8550: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
8560: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8570: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
8580: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8590: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
85a0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
85b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
85c0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
85d0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
85e0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
85f0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
8600: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8610: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
8620: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
8630: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
8640: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
8650: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8660: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
8670: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
8680: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8690: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
86a0: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
86b0: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
86c0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
86d0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
86e0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
86f0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
8700: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
8710: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
8720: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
8730: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
8740: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
8750: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
8760: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
8770: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
8780: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
8790: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
87a0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
87b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
87c0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
87d0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
87e0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
87f0: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
8800: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
8810: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
8820: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
8830: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
8840: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8850: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
8860: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
8870: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
8880: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
8890: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
88a0: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
88b0: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
88c0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
88d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
88e0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
88f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8900: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
8910: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
8920: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
8930: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
8940: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
8950: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
8960: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
8970: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
8980: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
8990: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
89a0: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
89b0: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
89c0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
89d0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
89e0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
89f0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
8a00: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
8a10: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
8a20: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
8a30: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
8a40: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
8a50: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
8a60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
8a70: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
8a80: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
8a90: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
8aa0: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
8ab0: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
8ac0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
8ad0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
8ae0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
8af0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
8b00: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
8b10: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
8b20: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
8b30: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
8b40: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
8b50: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
8b60: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
8b70: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
8b80: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
8b90: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
8ba0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
8bb0: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
8bc0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
8bd0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
8be0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
8bf0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
8c00: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
8c10: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
8c20: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
8c30: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
8c40: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
8c50: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
8c60: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
8c70: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
8c80: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
8c90: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
8ca0: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
8cb0: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
8cc0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
8cd0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
8ce0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
8cf0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
8d00: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
8d10: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
8d20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8d30: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
8d40: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
8d50: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
8d60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d70: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
8d80: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
8d90: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
8da0: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
8db0: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
8dc0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
8dd0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
8de0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
8df0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
8e00: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
8e10: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
8e20: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
8e30: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
8e40: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
8e50: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8e60: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
8e70: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
8e80: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
8e90: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
8ea0: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
8eb0: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
8ec0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
8ed0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
8ee0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
8ef0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
8f00: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
8f10: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
8f20: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
8f30: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
8f40: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
8f50: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
8f60: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
8f70: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8f80: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
8f90: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
8fa0: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
8fb0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
8fc0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
8fd0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
8fe0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8ff0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9000: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9010: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9020: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9030: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9040: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
9050: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
9060: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
9070: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
9080: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
9090: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
90a0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
90b0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
90c0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
90d0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
90e0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
90f0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
9100: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9110: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
9120: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9130: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9140: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
9150: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
9160: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
9170: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
9180: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
9190: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
91a0: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
91b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
91c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
91d0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
91e0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
91f0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
9200: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
9210: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9220: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9230: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9240: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9250: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9260: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9270: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9280: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
9290: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
92a0: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
92b0: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
92c0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
92d0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
92e0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
92f0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
9300: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
9310: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
9320: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9330: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
9340: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9350: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
9360: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
9370: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
9380: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
9390: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
93a0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
93b0: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
93c0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
93d0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
93e0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
93f0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
9400: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
9410: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
9420: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
9430: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
9440: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
9450: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9460: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9470: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9480: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
9490: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
94a0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
94b0: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
94c0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
94d0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
94e0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
94f0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
9500: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
9510: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
9520: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
9530: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
9540: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
9550: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
9560: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
9570: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
9580: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
9590: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
95a0: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
95b0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
95c0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
95d0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
95e0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
95f0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
9600: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
9610: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
9620: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
9630: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
9640: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
9650: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
9660: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
9670: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
9680: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
9690: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
96a0: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
96b0: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
96c0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
96d0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
96e0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
96f0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
9700: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
9710: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
9720: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9730: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
9740: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
9750: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
9760: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
9770: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
9780: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
9790: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
97a0: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
97b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
97c0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
97d0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
97e0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
97f0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
9800: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
9810: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
9820: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
9830: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
9840: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
9850: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
9860: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
9870: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
9880: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
9890: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
98a0: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
98b0: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
98c0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
98d0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
98e0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
98f0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
9900: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
9910: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
9920: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
9930: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
9940: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
9950: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
9960: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
9970: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
9980: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
9990: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
99a0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
99b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
99c0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
99d0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
99e0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
99f0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
9a00: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
9a10: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
9a20: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
9a30: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
9a40: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9a60: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
9a70: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
9a80: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
9a90: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
9aa0: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
9ab0: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
9ac0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ad0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
9ae0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
9af0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
9b00: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
9b10: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
9b20: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
9b30: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
9b40: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
9b50: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
9b60: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
9b70: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
9b80: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
9b90: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9ba0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
9bb0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
9bc0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
9bd0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
9be0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
9bf0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
9c00: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
9c10: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
9c20: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
9c30: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
9c40: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
9c50: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
9c60: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
9c70: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
9c80: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9c90: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9ca0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
9cb0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
9cc0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
9cd0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
9ce0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
9cf0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
9d00: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
9d10: 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  nts..** </ul>.*/
9d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d30: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
9d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
9d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
9d60: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
9d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
9d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
9d90: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
9da0: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
9db0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
9dc0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
9dd0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
9de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9df0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
9e00: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
9e10: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
9e20: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
9e30: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
9e40: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
9e50: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
9e60: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
9e70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
9e80: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
9e90: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
9ea0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
9eb0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
9ec0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
9ed0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9ee0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
9ef0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
9f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9f10: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
9f20: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
9f30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
9f40: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
9f50: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
9f60: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f70: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
9f80: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
9f90: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
9fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9fb0: 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  14../*.** CAPI3R
9fc0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
9fd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
9fe0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
9ff0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
a000: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
a010: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
a020: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
a030: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
a040: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
a050: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
a060: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
a070: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
a080: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
a090: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
a0a0: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
a0b0: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
a0c0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
a0d0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
a0e0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
a0f0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
a100: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
a110: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
a120: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
a130: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
a140: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
a150: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
a160: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
a170: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
a180: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
a190: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
a1a0: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
a1b0: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
a1c0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
a1d0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
a1e0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
a1f0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
a200: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
a210: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
a220: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
a230: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
a240: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
a250: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
a260: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
a270: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
a280: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
a290: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
a2a0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
a2b0: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
a2c0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
a2d0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
a2e0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a2f0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
a300: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
a310: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
a320: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
a330: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
a340: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
a350: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
a360: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
a370: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
a380: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
a390: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
a3a0: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
a3b0: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
a3c0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
a3d0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
a3e0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
a3f0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
a400: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
a410: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
a420: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
a430: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
a440: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
a450: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
a460: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
a470: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
a480: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
a490: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
a4a0: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
a4b0: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
a4c0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
a4d0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
a4e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
a4f0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
a500: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
a510: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
a520: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
a530: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
a540: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
a550: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
a560: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
a570: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
a580: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
a590: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
a5a0: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
a5b0: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
a5c0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
a5d0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
a5e0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
a5f0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
a600: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
a610: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
a620: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
a630: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
a640: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
a650: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
a660: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
a670: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
a680: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
a690: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
a6a0: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
a6b0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
a6c0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
a6d0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
a6e0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
a6f0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
a700: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
a710: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
a720: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
a730: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
a740: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
a750: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
a760: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
a770: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
a780: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
a790: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
a7a0: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
a7b0: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
a7c0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
a7d0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
a7e0: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
a7f0: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
a800: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
a810: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
a820: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
a830: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
a840: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
a850: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
a860: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
a870: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
a880: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
a890: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
a8a0: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
a8b0: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
a8c0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
a8d0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
a8e0: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
a8f0: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
a900: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
a910: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
a920: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
a930: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
a940: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
a950: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
a960: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
a970: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
a980: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
a990: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
a9a0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
a9b0: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
a9c0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
a9d0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
a9e0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
a9f0: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
aa00: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
aa10: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
aa20: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
aa30: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
aa40: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
aa50: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
aa60: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
aa70: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
aa80: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
aa90: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
aaa0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
aab0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
aac0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
aad0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
aae0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
aaf0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
ab00: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ab10: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
ab20: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
ab30: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
ab40: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
ab50: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
ab60: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
ab70: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
ab80: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
ab90: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
aba0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
abb0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
abc0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
abd0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
abe0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
abf0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
ac00: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
ac10: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
ac20: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
ac30: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
ac40: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
ac50: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
ac60: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
ac70: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
ac80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
ac90: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
aca0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
acb0: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
acc0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
acd0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
ace0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
acf0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
ad00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
ad10: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ad20: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
ad30: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ad40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
ad50: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
ad60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
ad70: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
ad80: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ad90: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
ada0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
adb0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
adc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
add0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
ade0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
adf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
ae00: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
ae10: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
ae20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
ae30: 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
ae40: 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
ae50: 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
ae60: 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
ae70: 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
ae80: 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
ae90: 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
aea0: 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
aeb0: 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
aec0: 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
aed0: 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
aee0: 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
aef0: 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
af00: 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
af10: 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
af20: 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
af30: 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
af40: 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
af50: 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
af60: 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
af70: 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
af80: 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
af90: 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
afa0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
afb0: 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
afc0: 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
afd0: 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
afe0: 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
aff0: 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
b000: 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
b010: 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
b020: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
b030: 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
b040: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
b050: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
b060: 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
b070: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
b080: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
b090: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
b0a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
b0b0: 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
b0c0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
b0d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
b0e0: 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
b0f0: 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
b100: 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
b110: 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
b120: 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
b130: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
b140: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
b150: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
b160: 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
b170: 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
b180: 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
b190: 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
b1a0: 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
b1b0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b1c0: 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
b1d0: 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
b1e0: 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
b1f0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
b200: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
b210: 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
b220: 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
b230: 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
b240: 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
b250: 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
b260: 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
b270: 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
b280: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
b290: 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
b2a0: 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
b2b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
b2c0: 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
b2d0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
b2e0: 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
b2f0: 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
b300: 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
b310: 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
b320: 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
b330: 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
b340: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
b350: 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
b360: 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
b370: 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
b380: 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
b390: 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
b3a0: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
b3b0: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
b3c0: 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
b3d0: 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
b3e0: 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
b3f0: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
b400: 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
b410: 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
b420: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
b430: 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
b440: 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
b450: 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
b460: 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
b470: 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
b480: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
b490: 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
b4a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
b4b0: 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
b4c0: 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
b4d0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
b4e0: 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
b4f0: 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
b500: 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
b510: 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
b520: 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
b530: 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
b540: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
b550: 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
b560: 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
b570: 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
b580: 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
b590: 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
b5a0: 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
b5b0: 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
b5c0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
b5d0: 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
b5e0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
b5f0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
b600: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
b610: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
b620: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
b630: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
b640: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
b650: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
b660: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
b670: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
b680: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
b690: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
b6a0: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
b6b0: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
b6c0: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
b6d0: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
b6e0: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
b6f0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
b700: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
b710: 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
b720: 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
b730: 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
b740: 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
b750: 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
b760: 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
b770: 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
b780: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
b790: 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
b7a0: 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
b7b0: 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
b7c0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
b7d0: 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
b7e0: 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
b7f0: 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
b800: 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
b810: 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
b820: 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
b830: 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
b840: 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
b850: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
b860: 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
b870: 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
b880: 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
b890: 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
b8a0: 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
b8b0: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
b8c0: 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
b8d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
b8e0: 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
b8f0: 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
b900: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
b910: 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
b920: 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
b930: 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
b940: 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
b950: 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
b960: 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
b970: 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
b980: 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
b990: 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
b9a0: 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
b9b0: 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
b9c0: 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
b9d0: 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
b9e0: 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
b9f0: 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
ba00: 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
ba10: 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
ba20: 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
ba30: 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
ba40: 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
ba50: 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
ba60: 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
ba70: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
ba80: 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
ba90: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
baa0: 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
bab0: 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
bac0: 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
bad0: 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
bae0: 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
baf0: 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
bb00: 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
bb10: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
bb20: 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
bb30: 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
bb40: 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
bb50: 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
bb60: 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
bb70: 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
bb80: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
bb90: 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
bba0: 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
bbb0: 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
bbc0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
bbd0: 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
bbe0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
bbf0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
bc00: 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
bc10: 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
bc20: 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
bc30: 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
bc40: 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
bc50: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
bc60: 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
bc70: 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
bc80: 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
bc90: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
bca0: 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
bcb0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
bcc0: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
bcd0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
bce0: 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
bcf0: 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
bd00: 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
bd10: 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
bd20: 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
bd30: 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
bd40: 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
bd50: 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
bd60: 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
bd70: 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
bd80: 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
bd90: 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
bda0: 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
bdb0: 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
bdc0: 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
bdd0: 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
bde0: 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
bdf0: 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
be00: 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
be10: 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
be20: 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
be30: 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
be40: 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
be50: 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
be60: 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
be70: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
be80: 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
be90: 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
bea0: 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
beb0: 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
bec0: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
bed0: 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
bee0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
bef0: 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
bf00: 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
bf10: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
bf20: 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
bf30: 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
bf40: 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
bf50: 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
bf60: 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
bf70: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
bf80: 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
bf90: 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
bfa0: 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
bfb0: 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
bfc0: 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
bfd0: 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
bfe0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bff0: 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
c000: 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
c010: 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
c020: 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
c030: 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
c040: 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
c050: 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
c060: 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
c070: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
c080: 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
c090: 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
c0a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
c0b0: 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
c0c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
c0d0: 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
c0e0: 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
c0f0: 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
c100: 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
c110: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
c120: 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
c130: 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
c140: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
c150: 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
c160: 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
c170: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
c180: 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
c190: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
c1a0: 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
c1b0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
c1c0: 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
c1d0: 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
c1e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
c1f0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
c200: 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
c210: 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
c220: 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
c230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
c240: 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
c250: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
c260: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
c270: 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
c280: 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
c290: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
c2a0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
c2b0: 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
c2c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
c2d0: 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
c2e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
c2f0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
c300: 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
c310: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
c320: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
c330: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
c340: 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
c350: 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
c360: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
c370: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
c380: 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
c390: 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
c3a0: 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
c3b0: 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
c3c0: 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
c3d0: 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
c3e0: 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
c3f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
c400: 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
c410: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
c420: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
c430: 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
c440: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
c450: 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
c460: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
c470: 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
c480: 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
c490: 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
c4a0: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
c4b0: 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
c4c0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
c4d0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
c4e0: 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
c4f0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
c500: 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
c510: 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
c520: 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
c530: 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
c540: 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
c550: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
c560: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
c570: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
c580: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
c590: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
c5a0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
c5b0: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
c5c0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
c5d0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
c5e0: 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
c5f0: 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
c600: 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
c610: 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
c620: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
c630: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c640: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
c650: 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
c660: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
c670: 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
c680: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
c690: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
c6a0: 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
c6b0: 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
c6c0: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
c6d0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
c6e0: 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
c6f0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
c700: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
c710: 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
c720: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
c730: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
c740: 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
c750: 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
c760: 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
c770: 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
c780: 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
c790: 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
c7a0: 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
c7b0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
c7c0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
c7d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
c7e0: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
c7f0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
c800: 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
c810: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
c820: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
c830: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
c840: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
c850: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
c860: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
c870: 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
c880: 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
c890: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
c8a0: 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
c8b0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
c8c0: 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
c8d0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
c8e0: 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
c8f0: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
c900: 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
c910: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c920: 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
c930: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
c940: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
c950: 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
c960: 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
c970: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
c980: 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
c990: 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
c9a0: 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
c9b0: 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
c9c0: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
c9d0: 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
c9e0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
c9f0: 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
ca00: 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
ca10: 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
ca20: 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
ca30: 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
ca40: 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
ca50: 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
ca60: 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
ca70: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
ca80: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ca90: 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
caa0: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
cab0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
cac0: 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
cad0: 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
cae0: 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
caf0: 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
cb00: 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
cb10: 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
cb20: 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
cb30: 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
cb40: 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
cb50: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
cb60: 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
cb70: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
cb80: 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
cb90: 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
cba0: 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
cbb0: 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
cbc0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
cbd0: 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
cbe0: 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
cbf0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
cc00: 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
cc10: 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
cc20: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
cc30: 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
cc40: 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
cc50: 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
cc60: 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
cc70: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
cc80: 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
cc90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
cca0: 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
ccb0: 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
ccc0: 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
ccd0: 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
cce0: 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
ccf0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
cd00: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
cd10: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
cd20: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
cd30: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
cd40: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
cd50: 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
cd60: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
cd70: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
cd80: 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
cd90: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
cda0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
cdb0: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
cdc0: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
cdd0: 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
cde0: 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
cdf0: 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
ce00: 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
ce10: 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
ce20: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
ce30: 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
ce40: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
ce50: 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
ce60: 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
ce70: 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
ce80: 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
ce90: 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
cea0: 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
ceb0: 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
cec0: 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
ced0: 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
cee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
cef0: 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
cf00: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
cf10: 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
cf20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
cf30: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
cf40: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
cf50: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
cf60: 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
cf70: 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
cf80: 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
cf90: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
cfa0: 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
cfb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
cfc0: 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
cfd0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
cfe0: 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
cff0: 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
d000: 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
d010: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
d020: 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
d030: 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
d040: 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
d050: 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
d060: 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
d080: 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
d090: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
d0a0: 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
d0b0: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
d0c0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
d0d0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
d0e0: 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
d0f0: 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
d100: 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
d110: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d120: 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
d130: 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
d140: 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
d150: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
d160: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d170: 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
d180: 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
d190: 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
d1a0: 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
d1b0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
d1c0: 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
d1d0: 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
d1e0: 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
d1f0: 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
d200: 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
d210: 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
d220: 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
d230: 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
d240: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
d250: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d260: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
d270: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
d280: 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
d290: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
d2a0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
d2b0: 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
d2c0: 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
d2d0: 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
d2e0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
d2f0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
d300: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
d310: 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
d320: 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
d330: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
d340: 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
d350: 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
d360: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d370: 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
d380: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
d390: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
d3a0: 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
d3b0: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
d3c0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d3d0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
d3e0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
d3f0: 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
d400: 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
d410: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d420: 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
d430: 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
d440: 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
d450: 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
d460: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
d470: 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
d480: 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
d490: 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
d4a0: 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
d4b0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
d4c0: 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
d4d0: 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
d4e0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
d4f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
d500: 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
d510: 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
d520: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
d530: 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
d540: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
d550: 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
d560: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
d570: 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
d580: 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
d590: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d5a0: 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
d5b0: 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
d5c0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
d5d0: 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
d5e0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
d5f0: 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
d600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
d610: 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
d620: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
d630: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d640: 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
d650: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
d660: 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
d670: 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
d680: 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
d690: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
d6a0: 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
d6b0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d6c0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
d6d0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d6e0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
d6f0: 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
d700: 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
d710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
d720: 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
d730: 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
d740: 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
d750: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
d760: 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
d770: 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
d780: 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
d790: 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
d7a0: 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
d7b0: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
d7c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
d7d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
d7e0: 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
d7f0: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
d800: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
d810: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
d820: 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
d830: 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
d840: 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
d850: 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
d860: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
d870: 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
d880: 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
d890: 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
d8a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d8b0: 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
d8c0: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
d8d0: 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
d8e0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
d8f0: 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
d900: 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
d910: 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
d920: 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
d930: 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
d940: 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
d950: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
d960: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
d970: 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
d980: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
d990: 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
d9a0: 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
d9b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d9c0: 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
d9d0: 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
d9e0: 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
d9f0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
da00: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
da10: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
da20: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
da30: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
da40: 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
da50: 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
da60: 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
da70: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
da80: 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
da90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
daa0: 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
dab0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
dac0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
dad0: 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
dae0: 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
daf0: 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
db00: 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
db10: 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
db20: 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
db30: 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
db40: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
db50: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
db60: 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
db70: 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
db80: 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
db90: 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
dba0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
dbb0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
dbc0: 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
dbd0: 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
dbe0: 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
dbf0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
dc00: 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
dc10: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
dc20: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
dc30: 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
dc40: 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
dc50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
dc60: 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
dc70: 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
dc80: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
dc90: 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
dca0: 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
dcb0: 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
dcc0: 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
dcd0: 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
dce0: 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
dcf0: 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
dd00: 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
dd10: 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
dd20: 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
dd30: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
dd40: 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
dd50: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
dd60: 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
dd70: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
dd80: 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
dd90: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
dda0: 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
ddb0: 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
ddc0: 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
ddd0: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
dde0: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
ddf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
de00: 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
de10: 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
de20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
de30: 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
de40: 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
de50: 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
de60: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
de70: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
de80: 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
de90: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
dea0: 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
deb0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
dec0: 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
ded0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
dee0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
def0: 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
df00: 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
df10: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
df20: 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
df30: 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
df40: 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
df50: 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
df60: 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
df70: 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
df80: 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
df90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
dfa0: 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
dfb0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
dfc0: 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
dfd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
dfe0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
dff0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
e000: 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
e010: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
e020: 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
e030: 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
e040: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
e050: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
e060: 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
e070: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
e080: 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
e090: 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
e0a0: 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
e0b0: 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
e0c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69   int sqlite3_ini
e0d0: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53  tialize(void);.S
e0e0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
e0f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
e100: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
e110: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
e120: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
e130: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
e140: 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
e150: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e160: 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
e170: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
e180: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
e190: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
e1a0: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
e1b0: 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
e1c0: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
e1d0: 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
e1e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
e1f0: 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
e200: 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
e210: 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
e220: 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
e230: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
e240: 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
e250: 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
e260: 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
e270: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
e280: 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
e290: 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
e2a0: 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
e2b0: 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
e2c0: 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
e2d0: 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
e2e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
e2f0: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
e300: 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
e310: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
e320: 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
e330: 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
e340: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e350: 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
e360: 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
e370: 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
e380: 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
e390: 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
e3a0: 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
e3b0: 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
e3c0: 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
e3d0: 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
e3e0: 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
e3f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
e400: 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
e410: 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
e420: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e430: 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
e440: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
e450: 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
e460: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
e470: 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
e480: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
e490: 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
e4a0: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
e4b0: 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
e4c0: 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
e4d0: 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
e4e0: 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
e4f0: 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
e500: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
e510: 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
e520: 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
e530: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
e540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
e550: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
e560: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
e570: 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
e580: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
e590: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
e5a0: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
e5b0: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
e5c0: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
e5d0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
e5e0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
e5f0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
e600: 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
e610: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
e620: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
e630: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
e640: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
e650: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
e660: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
e670: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
e680: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
e690: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
e6a0: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
e6b0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
e6c0: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
e6d0: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
e6e0: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
e6f0: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
e700: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
e710: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
e720: 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
e730: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
e740: 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
e750: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
e760: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
e770: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
e780: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
e790: 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
e7a0: 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
e7b0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
e7c0: 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
e7d0: 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
e7e0: 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
e7f0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
e800: 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
e810: 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
e820: 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
e830: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e840: 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
e850: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e860: 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
e870: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
e880: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
e890: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
e8a0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
e8b0: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
e8c0: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
e8d0: 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
e8e0: 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
e8f0: 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
e900: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
e910: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e920: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
e930: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
e940: 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
e950: 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
e960: 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
e970: 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
e980: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
e990: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
e9a0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
e9b0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
e9c0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
e9d0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
e9e0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
e9f0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
ea00: 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
ea10: 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
ea20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ea30: 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
ea40: 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
ea50: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
ea60: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
ea70: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
ea80: 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
ea90: 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
eaa0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
eab0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
eac0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
ead0: 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
eae0: 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
eaf0: 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
eb00: 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
eb10: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
eb20: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
eb30: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
eb40: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
eb50: 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
eb60: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
eb70: 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
eb80: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
eb90: 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
eba0: 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
ebb0: 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
ebc0: 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
ebd0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
ebe0: 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
ebf0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
ec00: 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
ec10: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
ec20: 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
ec30: 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
ec40: 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
ec50: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
ec60: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
ec70: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
ec80: 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
ec90: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
eca0: 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
ecb0: 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
ecc0: 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
ecd0: 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
ece0: 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
ecf0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
ed00: 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
ed10: 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
ed20: 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
ed30: 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
ed40: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
ed50: 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
ed60: 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
ed70: 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
ed80: 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
ed90: 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
eda0: 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
edb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
edc0: 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
edd0: 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
ede0: 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
edf0: 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
ee00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
ee10: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
ee20: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
ee30: 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
ee40: 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
ee50: 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
ee60: 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
ee70: 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
ee80: 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
ee90: 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
eea0: 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
eeb0: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
eec0: 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
eed0: 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
eee0: 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
eef0: 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
ef00: 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
ef10: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
ef20: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
ef30: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
ef40: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
ef50: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
ef60: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
ef70: 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
ef80: 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
ef90: 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
efa0: 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
efb0: 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
efc0: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
efd0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
efe0: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
eff0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
f000: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
f010: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
f020: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
f030: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
f040: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
f050: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
f060: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
f070: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
f080: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
f090: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
f0a0: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
f0b0: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
f0c0: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
f0d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f0e0: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
f0f0: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
f100: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
f110: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
f120: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
f130: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
f140: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
f150: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
f160: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
f170: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
f180: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
f190: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
f1a0: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
f1b0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f1c0: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
f1d0: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
f1e0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
f1f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
f200: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
f210: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
f220: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
f230: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
f240: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
f250: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
f260: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
f270: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
f280: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
f290: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
f2a0: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
f2b0: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
f2c0: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
f2d0: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
f2e0: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
f2f0: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
f300: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
f310: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
f320: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
f330: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
f340: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
f350: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
f360: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
f370: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
f380: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
f390: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
f3a0: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
f3b0: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
f3c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
f3d0: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
f3e0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
f3f0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
f400: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
f410: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
f420: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
f430: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
f440: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
f450: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
f460: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
f470: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
f480: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
f490: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
f4a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
f4b0: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
f4c0: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
f4d0: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
f4e0: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
f4f0: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
f500: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
f510: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
f520: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
f530: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
f540: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
f550: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
f560: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
f570: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
f580: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
f590: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
f5a0: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
f5b0: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
f5c0: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
f5d0: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
f5e0: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
f5f0: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
f600: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
f610: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
f620: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
f630: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
f640: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
f650: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
f660: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
f670: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
f680: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
f690: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
f6a0: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
f6b0: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
f6c0: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
f6d0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
f6e0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
f6f0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f700: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
f710: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
f720: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
f730: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
f740: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
f750: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
f760: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
f770: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
f780: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
f790: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
f7a0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
f7b0: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
f7c0: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
f7d0: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
f7e0: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
f7f0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
f800: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
f810: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
f820: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
f830: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
f840: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
f850: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
f860: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
f870: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
f880: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
f890: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
f8a0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
f8b0: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
f8c0: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
f8d0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
f8e0: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
f8f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
f900: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
f910: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
f920: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
f930: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
f940: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
f950: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
f960: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
f970: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
f980: 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
f990: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
f9a0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
f9b0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
f9c0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
f9d0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f9e0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
f9f0: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
fa00: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
fa10: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
fa20: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
fa30: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
fa40: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fa50: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
fa60: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
fa70: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
fa80: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
fa90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
faa0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
fab0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
fac0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
fad0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
fae0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
faf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
fb00: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
fb10: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
fb20: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
fb30: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
fb40: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
fb50: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
fb60: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
fb70: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
fb80: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
fb90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fba0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
fbb0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
fbc0: 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
fbd0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
fbe0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
fbf0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
fc00: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
fc10: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
fc20: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
fc30: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
fc40: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
fc50: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
fc60: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
fc70: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
fc80: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
fc90: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
fca0: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
fcb0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
fcc0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
fcd0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
fce0: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
fcf0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
fd00: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
fd10: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
fd20: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
fd30: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
fd40: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
fd50: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
fd60: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
fd70: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
fd80: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
fd90: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
fda0: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
fdb0: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
fdc0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
fdd0: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
fde0: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
fdf0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
fe00: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
fe10: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
fe20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
fe30: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
fe40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
fe50: 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
fe60: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
fe70: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
fe80: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
fe90: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
fea0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
feb0: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
fec0: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
fed0: 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
fee0: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
fef0: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
ff00: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
ff10: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
ff20: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
ff30: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ff40: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
ff50: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
ff60: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
ff70: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
ff80: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
ff90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
ffa0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
ffb0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
ffc0: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
ffd0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
ffe0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
fff0: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
10000 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
10010 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
10020 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
10030 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
10040 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
10050 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
10060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
10070 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
10080 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
10090 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
100a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
100b0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
100c0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
100d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
100e0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
100f0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
10100 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
10110 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
10120 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
10130 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10140 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
10150 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
10160 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
10170 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
10180 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
10190 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
101a0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
101b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
101c0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
101d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
101e0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
101f0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
10200 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
10210 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
10220 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
10230 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
10240 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
10250 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
10260 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
10270 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
10280 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
10290 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
102a0 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
102b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
102c0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
102d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
102e0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
102f0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
10300 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
10310 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10320 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
10330 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
10340 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
10350 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
10360 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
10370 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
10380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
10390 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
103a0 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
103b0 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
103c0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
103d0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
103e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
103f0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
10400 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
10410 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
10420 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
10430 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
10440 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
10450 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
10460 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
10470 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
10480 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
10490 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
104a0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
104b0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
104c0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
104d0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
104e0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
104f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
10500 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
10510 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
10520 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
10530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
10540 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
10550 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
10560 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10570 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
10580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10590 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
105a0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
105b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
105c0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
105d0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
105e0 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
105f0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
10600 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
10610 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
10620 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
10630 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
10640 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
10650 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
10660 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
10670 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
10680 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10690 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
106a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
106b0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
106c0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
106d0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
106e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
106f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
10700 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
10710 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
10720 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
10730 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
10740 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10750 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10760 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
10770 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
10780 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
10790 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
107a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
107b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
107c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
107d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
107e0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
107f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
10800 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10810 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
10820 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
10830 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
10840 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
10850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10860 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
10870 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
10880 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
10890 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
108a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
108b0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
108c0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
108d0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
108e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
108f0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
10900 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
10910 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
10920 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
10940 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
10950 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
10960 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
10970 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
10980 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
10990 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
109a0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
109b0 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
109c0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
109d0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
109e0 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
109f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
10a00 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
10a10 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
10a20 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
10a30 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
10a40 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
10a50 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10a60 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
10a70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
10a80 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
10a90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
10aa0 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
10ab0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
10ac0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
10ad0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
10ae0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
10af0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
10b00 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
10b10 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
10b20 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
10b30 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
10b40 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
10b50 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
10b60 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
10b70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
10b80 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
10b90 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
10ba0 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
10bb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
10bc0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
10bd0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
10be0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
10bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
10c00 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
10c10 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
10c20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
10c30 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
10c40 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
10c50 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
10c60 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
10c70 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
10c80 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
10c90 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
10ca0 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
10cb0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
10cc0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
10cd0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
10ce0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
10cf0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
10d00 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
10d10 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
10d20 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
10d30 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
10d40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
10d50 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
10d60 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
10d70 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
10d80 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
10d90 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
10da0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
10db0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
10dc0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
10dd0 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
10de0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
10df0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
10e00 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
10e10 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
10e20 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
10e30 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
10e40 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
10e50 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
10e60 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
10e70 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
10e80 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
10e90 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
10ea0 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
10eb0 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
10ec0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
10ed0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
10ee0 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
10ef0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
10f00 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
10f10 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
10f20 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
10f30 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
10f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f50 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
10f60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
10f70 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
10f80 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
10f90 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
10fa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10fb0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
10fc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10fd0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
10fe0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
10ff0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
11000 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
11010 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
11020 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
11030 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
11040 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
11050 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
11060 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
11070 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
11080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
11090 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
110a0 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
110b0 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
110c0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
110d0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
110e0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
110f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
11100 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  2 option..** The
11110 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
11120 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11130 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
11140 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
11150 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
11160 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
11170 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
11180 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
11190 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
111a0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
111b0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
111c0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
111d0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
111e0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
111f0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
11200 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
11210 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
11220 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
11230 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
11240 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
11250 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
11260 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
11270 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
11280 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
11290 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
112a0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
112b0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
112c0 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
112d0 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
112e0 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
112f0 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
11300 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
11310 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
11320 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
11330 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11340 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
11350 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
11360 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11370 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
11380 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
11390 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
113a0 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
113b0 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
113c0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
113d0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
113e0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
113f0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
11400 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
11410 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
11420 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
11430 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
11440 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
11450 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
11460 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
11470 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11480 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
11490 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
114a0 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
114b0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
114c0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
114d0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
114e0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
114f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
11500 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
11510 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
11520 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11530 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11540 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11550 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11560 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
11570 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
11580 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
11590 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
115a0 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
115b0 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
115c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
115d0 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
115e0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
115f0 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
11600 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
11610 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
11620 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
11630 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
11640 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
11650 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
11660 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
11670 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
11680 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
11690 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
116a0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
116b0 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
116c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
116d0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
116e0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
116f0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
11700 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
11710 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
11720 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
11730 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
11740 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
11750 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
11760 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
11770 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
11780 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
11790 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
117a0 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
117b0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
117c0 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
117d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
117e0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
117f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
11800 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
11810 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
11820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11830 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
11840 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
11850 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
11860 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
11870 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
11880 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
11890 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
118a0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
118b0 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
118c0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
118d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
118e0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
118f0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
11900 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
11910 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
11920 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
11930 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
11940 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11950 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
11960 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11970 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
11980 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
119a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
119b0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
119c0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
119d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
119e0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
119f0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11a00 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
11a10 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
11a20 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
11a30 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
11a40 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
11a50 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
11a60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
11a70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
11a80 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
11a90 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
11aa0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
11ab0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
11ac0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
11ad0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
11ae0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
11af0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
11b00 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11b10 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11b20 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11b30 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11b40 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11b50 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11b60 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
11b70 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
11b80 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
11b90 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
11ba0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
11bb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
11bc0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
11bd0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11be0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
11bf0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
11c00 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
11c10 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
11c20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11c30 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
11c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11c50 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
11c60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
11c70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
11c80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
11c90 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
11ca0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
11cb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
11cc0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
11cd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11ce0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
11cf0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
11d00 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
11d10 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
11d20 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
11d30 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
11d40 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
11d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
11d60 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
11d70 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
11d80 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
11d90 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
11da0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
11db0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
11dc0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
11dd0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
11de0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
11df0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
11e00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
11e10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
11e20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
11e30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
11e40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
11e50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
11e60 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
11e70 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
11e80 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
11e90 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
11ea0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
11eb0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
11ec0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
11ed0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
11ee0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11ef0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
11f00 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
11f10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11f20 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
11f30 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
11f40 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
11f50 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
11f60 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
11f70 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
11f80 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
11f90 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
11fa0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11fb0 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
11fc0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
11fd0 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
11fe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11ff0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
12000 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
12010 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
12020 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
12030 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
12040 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
12050 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
12060 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
12070 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
12080 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
12090 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
120a0 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
120b0 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
120c0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
120d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
120e0 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
120f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
12100 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
12110 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
12120 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
12130 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
12140 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
12150 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
12160 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12170 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
12180 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
12190 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
121a0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
121b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
121c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
121d0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
121e0 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
121f0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
12200 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
12210 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
12220 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
12230 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
12240 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
12250 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
12260 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12270 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
12280 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
12290 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
122a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
122b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
122c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
122d0 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
122e0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
122f0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
12300 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12310 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12320 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12330 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
12340 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
12350 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
12360 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
12370 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
12380 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
12390 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
123a0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
123b0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
123c0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
123d0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
123e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
123f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
12400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
12410 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
12420 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
12430 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
12440 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
12450 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
12460 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
12470 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
12480 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
12490 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
124a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
124b0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
124c0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
124d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
124e0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
124f0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
12500 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
12510 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
12520 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
12530 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
12540 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
12550 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
12560 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
12570 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
12580 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
12590 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
125a0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
125b0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
125c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
125d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
125e0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
125f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
12600 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
12610 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
12620 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
12630 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
12640 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
12650 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
12660 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
12670 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12680 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
12690 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
126a0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
126b0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
126c0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
126d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
126e0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
126f0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
12700 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
12710 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
12720 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
12730 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
12740 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
12750 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
12760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
12770 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
12780 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
12790 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
127a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
127b0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
127c0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
127d0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
127e0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
127f0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
12800 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
12810 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
12820 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
12830 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
12840 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12850 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
12860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
12870 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
12880 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
12890 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
128a0 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
128b0 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
128c0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
128d0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
128e0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
128f0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
12900 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
12910 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
12920 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
12930 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
12940 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
12950 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
12960 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
12970 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
12980 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
12990 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
129a0 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
129b0 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
129c0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
129d0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
129e0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
129f0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
12a00 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
12a10 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
12a20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
12a30 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
12a40 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
12a50 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
12a60 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
12a70 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
12a80 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
12a90 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
12aa0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
12ab0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
12ac0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
12ad0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
12ae0 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
12af0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
12b00 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
12b10 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
12b20 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
12b30 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
12b40 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
12b50 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
12b60 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
12b70 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
12b80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
12b90 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
12ba0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
12bb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12bc0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
12bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
12be0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
12bf0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
12c00 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
12c10 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
12c20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
12c30 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
12c40 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
12c50 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
12c60 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
12c70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
12c80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12c90 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
12ca0 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
12cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12cc0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12cd0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
12ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12cf0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
12d00 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
12d10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12d20 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
12d30 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
12d40 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
12d50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12d60 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12d70 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
12d80 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12d90 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
12da0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12db0 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
12dc0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
12dd0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
12df0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
12e00 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
12e10 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
12e20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
12e30 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
12e40 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
12e50 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
12e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12e70 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
12e80 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
12e90 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
12ea0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
12eb0 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
12ec0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
12ed0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
12ee0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
12ef0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
12f00 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
12f10 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
12f20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
12f30 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
12f40 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
12f50 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
12f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12f70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
12f80 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
12f90 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
12fa0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
12fb0 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
12fc0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
12fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12fe0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
12ff0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
13000 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13010 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
13020 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
13030 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
13040 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
13050 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
13060 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13080 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
13090 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
130a0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
130b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
130c0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
130d0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
130e0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
130f0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
13100 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
13110 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
13120 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
13130 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
13140 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
13150 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
13160 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13170 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
13180 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
13190 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
131a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
131b0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
131c0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
131d0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
131e0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
131f0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
13200 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
13210 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
13220 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13230 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
13240 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
13250 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
13260 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
13270 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
13280 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13290 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
132a0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
132b0 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
132c0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
132d0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
132e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
132f0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
13300 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
13310 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
13320 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
13330 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
13340 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
13350 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
13360 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
13370 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
13380 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
13390 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
133a0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
133b0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
133c0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
133d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
133e0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
133f0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
13400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13410 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
13420 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
13430 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
13440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
13450 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
13460 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
13470 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
13480 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
13490 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
134a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
134b0 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
134c0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
134d0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
134e0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
134f0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
13500 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
13510 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
13520 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
13530 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13540 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
13550 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
13560 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
13570 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
13580 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
13590 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
135a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
135b0 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
135c0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
135d0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
135e0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
135f0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
13600 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
13610 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
13620 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
13630 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
13640 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
13650 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13660 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
13670 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
13680 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
13690 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
136a0 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
136b0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
136c0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
136d0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
136e0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
136f0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
13700 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
13710 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
13720 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
13730 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
13740 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
13750 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
13760 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
13770 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
13780 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
13790 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
137a0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
137b0 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
137c0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
137d0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
137e0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
137f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13800 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
13810 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
13820 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
13830 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
13840 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
13850 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
13860 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
13870 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
13880 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
13890 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
138a0 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
138b0 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
138c0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
138d0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
138e0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
138f0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
13900 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
13910 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
13920 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
13930 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
13940 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
13950 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
13960 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
13970 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
13980 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13990 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
139a0 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
139b0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
139c0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
139d0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
139e0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
139f0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
13a00 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
13a10 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
13a20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13a30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13a40 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
13a50 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
13a60 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
13a70 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
13a80 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
13a90 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
13aa0 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
13ab0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
13ac0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
13ad0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
13ae0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
13af0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
13b00 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
13b10 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
13b20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
13b30 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
13b40 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
13b50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13b60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
13b70 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
13b80 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
13b90 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
13ba0 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
13bb0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
13bc0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
13bd0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
13be0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
13bf0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
13c00 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
13c10 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
13c20 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
13c30 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
13c40 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
13c50 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
13c60 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
13c70 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
13c80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
13c90 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
13ca0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
13cb0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
13cc0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
13cd0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
13ce0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
13cf0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
13d00 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13d10 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
13d20 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
13d30 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
13d40 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
13d50 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
13d60 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
13d70 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
13d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
13d90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
13da0 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
13db0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
13dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
13dd0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
13de0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
13df0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
13e00 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
13e10 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
13e20 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
13e30 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
13e40 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
13e50 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
13e60 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
13e70 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
13e80 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13e90 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
13ea0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
13eb0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
13ec0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
13ed0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
13ee0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
13ef0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
13f00 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
13f10 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
13f20 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
13f30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
13f40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
13f50 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
13f60 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
13f70 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
13f80 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
13f90 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
13fa0 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
13fb0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
13fc0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
13fd0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
13fe0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
13ff0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
14000 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
14010 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
14020 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
14030 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
14040 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
14050 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
14060 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
14070 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
14080 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
14090 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
140a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
140b0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
140c0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
140d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
140e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
140f0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
14100 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
14110 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
14120 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
14130 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
14140 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
14150 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
14160 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
14170 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
14180 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
14190 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
141a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
141b0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
141c0 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51  ment.  ^As of SQ
141d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
141e0 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .7, this routine
141f0 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65  s.** records the
14200 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
14210 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e  id of both ordin
14220 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b  ary tables and [
14230 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
14240 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
14250 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
14260 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
14270 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
14280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14290 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
142a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
142b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
142c0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
142d0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
142e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
142f0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
14300 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
14310 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
14320 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
14330 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
14340 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
14350 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
14360 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
14370 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
14380 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
14390 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
143a0 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
143b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
143c0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
143d0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
143e0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
143f0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
14400 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
14410 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
14420 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
14430 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
14440 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
14450 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
14460 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
14470 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
14480 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
14490 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
144a0 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
144b0 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
144c0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
144d0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
144e0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
144f0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
14500 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
14510 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
14520 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
14530 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
14540 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
14550 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
14560 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
14570 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
14580 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
14590 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
145a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
145b0 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
145c0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
145d0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
145e0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
145f0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
14600 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
14610 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
14620 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
14630 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
14640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
14650 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
14660 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
14670 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
14680 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
14690 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
146a0 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
146b0 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
146c0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
146d0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
146e0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
146f0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
14700 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
14710 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
14720 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
14730 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
14740 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
14750 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
14760 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
14770 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
14780 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
14790 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
147a0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
147b0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
147c0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
147d0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
147e0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
147f0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
14800 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
14810 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
14820 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
14830 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
14840 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
14850 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
14860 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
14870 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
14880 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
14890 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51  t [rowid]..*/.SQ
148a0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
148b0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
148c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
148d0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
148e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
148f0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
14900 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
14910 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
14920 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
14930 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
14940 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
14950 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
14960 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
14970 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
14980 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
14990 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
149a0 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
149b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
149c0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
149d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
149e0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
149f0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
14a00 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
14a10 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
14a20 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
14a30 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
14a40 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
14a50 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
14a60 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
14a70 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
14a80 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
14a90 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
14aa0 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
14ab0 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
14ac0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
14ad0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
14ae0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
14af0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
14b00 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
14b10 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
14b20 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
14b30 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
14b40 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
14b50 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
14b60 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
14b70 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
14b80 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
14b90 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
14ba0 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
14bb0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
14bc0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
14bd0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
14be0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
14bf0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
14c00 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
14c10 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
14c20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
14c30 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
14c40 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
14c50 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
14c60 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
14c70 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
14c80 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
14c90 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
14ca0 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
14cb0 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
14cc0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
14cd0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
14ce0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
14cf0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
14d00 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
14d10 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
14d20 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
14d30 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
14d40 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
14d50 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
14d60 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
14d70 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
14d80 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
14d90 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
14da0 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
14db0 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
14dc0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
14dd0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
14de0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
14df0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
14e00 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
14e10 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
14e20 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
14e30 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
14e40 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
14e50 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
14e60 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
14e70 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
14e80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
14e90 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
14ea0 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
14eb0 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
14ec0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
14ed0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
14ee0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
14ef0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14f00 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14f10 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
14f20 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
14f30 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
14f40 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
14f50 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
14f60 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
14f70 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
14f80 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
14f90 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
14fa0 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
14fb0 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
14fc0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
14fd0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
14fe0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
14ff0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
15000 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
15010 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
15020 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
15030 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
15040 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
15050 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
15060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
15070 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
15080 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
15090 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
150a0 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
150b0 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
150c0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
150d0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
150e0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
150f0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
15100 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
15110 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
15120 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
15130 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
15140 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
15150 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
15160 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
15170 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
15180 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
15190 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
151a0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
151b0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
151c0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
151d0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
151e0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
151f0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
15200 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
15210 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
15220 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
15230 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
15240 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15250 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15260 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
15270 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
15280 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
15290 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
152a0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
152b0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
152c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
152d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
152e0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
152f0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
15300 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
15310 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
15320 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
15330 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
15340 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
15350 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
15360 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
15370 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
15380 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
15390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
153a0 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
153b0 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
153c0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
153d0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
153e0 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
153f0 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
15400 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
15410 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
15420 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
15430 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
15440 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
15450 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
15460 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
15470 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
15480 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
15490 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
154a0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
154b0 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
154c0 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
154d0 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
154e0 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
154f0 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
15500 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
15510 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
15520 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
15530 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
15540 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
15550 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
15560 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
15570 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
15580 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
15590 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
155a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
155b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
155c0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
155d0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
155e0 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
155f0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
15600 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
15610 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
15620 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
15630 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
15640 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
15650 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
15660 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
15670 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
15680 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
15690 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
156a0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
156b0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
156c0 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
156d0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
156e0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
156f0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
15700 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
15710 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
15720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15730 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
15740 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
15750 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
15760 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
15770 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
15780 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
15790 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
157a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
157b0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
157c0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
157d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
157e0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
157f0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
15800 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
15810 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
15820 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
15830 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
15840 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
15850 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
15860 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
15870 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
15880 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
15890 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
158a0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
158b0 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
158c0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
158d0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
158e0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
158f0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
15900 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
15910 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
15920 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
15930 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
15940 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
15950 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
15960 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
15970 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
15980 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
15990 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
159a0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
159b0 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
159c0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
159d0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
159e0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
159f0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
15a00 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
15a10 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
15a20 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
15a30 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
15a40 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
15a50 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
15a60 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
15a70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
15a80 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
15a90 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
15aa0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
15ab0 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
15ac0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
15ad0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
15ae0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
15af0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
15b00 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
15b10 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
15b20 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
15b30 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
15b40 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
15b50 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
15b60 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
15b70 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
15b80 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
15b90 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
15ba0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
15bb0 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
15bc0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
15bd0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
15be0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
15bf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15c00 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
15c10 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
15c20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
15c30 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
15c40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
15c50 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15c60 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
15c70 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
15c80 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15c90 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15ca0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
15cb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
15cc0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
15cd0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
15ce0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
15cf0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
15d00 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
15d10 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
15d20 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
15d30 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
15d40 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
15d50 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
15d60 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
15d70 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
15d80 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
15d90 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
15da0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
15db0 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
15dc0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15dd0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
15de0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
15df0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
15e00 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
15e10 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
15e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
15e30 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
15e40 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
15e50 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
15e60 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
15e70 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
15e80 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
15e90 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
15ea0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
15eb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
15ec0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
15ed0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15ee0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
15ef0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
15f00 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
15f10 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
15f20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  I void sqlite3_i
15f30 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
15f40 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15f50 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
15f60 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
15f70 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
15f80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15f90 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
15fa0 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
15fb0 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
15fc0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
15fd0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
15fe0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
15ff0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
16000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
16010 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
16020 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
16030 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
16040 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
16050 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
16060 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
16070 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
16080 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
16090 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
160a0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
160b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
160c0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
160d0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
160e0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
160f0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
16100 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
16110 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
16120 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
16130 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
16140 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
16150 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
16160 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
16170 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
16180 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
16190 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
161a0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
161b0 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
161c0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
161d0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
161e0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
161f0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
16200 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
16210 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
16220 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
16230 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
16240 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
16250 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
16260 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
16270 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
16280 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
16290 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
162a0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
162b0 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
162c0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
162d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
162e0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
162f0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
16300 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
16310 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
16320 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
16330 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
16340 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
16350 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
16360 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
16370 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
16380 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
16390 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
163a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
163b0 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
163c0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
163d0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
163e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
163f0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
16400 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
16410 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
16420 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
16430 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
16440 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
16450 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
16460 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16470 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
16480 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
16490 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
164a0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
164b0 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
164c0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
164d0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
164e0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
164f0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
16500 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
16510 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
16520 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
16530 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
16540 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
16550 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
16560 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
16570 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
16580 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
16590 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
165a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
165b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
165c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
165d0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
165e0 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
165f0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
16600 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
16610 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
16620 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
16630 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
16640 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
16650 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
16660 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
16670 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
16680 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
16690 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
166a0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
166b0 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
166c0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
166d0 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
166e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
166f0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
16700 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
16710 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
16720 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
16730 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
16740 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
16750 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
16760 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
16770 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
16780 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
16790 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
167a0 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
167b0 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
167c0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
167d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
167e0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
167f0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
16800 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
16810 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
16820 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
16830 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
16840 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
16850 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
16860 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
16870 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
16880 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
16890 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
168a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
168b0 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
168c0 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
168d0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
168e0 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
168f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
16900 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
16910 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
16920 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
16930 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
16940 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
16950 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
16960 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
16970 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
16980 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
16990 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
169a0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
169b0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
169c0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
169d0 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
169e0 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
169f0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
16a00 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
16a10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
16a20 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
16a30 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
16a40 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
16a50 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
16a60 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
16a70 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
16a80 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
16a90 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
16aa0 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
16ab0 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
16ac0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
16ad0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
16ae0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
16af0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
16b00 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
16b10 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
16b20 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
16b30 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
16b40 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
16b50 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
16b60 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
16b70 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
16b80 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
16b90 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
16ba0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
16bb0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
16bc0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
16bd0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
16be0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
16bf0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
16c00 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
16c10 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
16c20 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
16c30 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
16c40 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
16c50 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
16c60 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
16c70 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
16c80 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
16c90 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
16ca0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
16cb0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
16cc0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
16cd0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
16ce0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
16cf0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
16d00 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
16d10 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
16d20 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
16d30 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
16d40 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
16d50 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
16d60 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
16d70 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
16d80 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
16d90 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
16da0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
16db0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
16dc0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
16dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
16de0 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
16df0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
16e00 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16e10 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
16e20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
16e30 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
16e40 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
16e50 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
16e60 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
16e70 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
16e80 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
16e90 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
16ea0 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
16eb0 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
16ec0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
16ed0 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
16ee0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
16ef0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
16f00 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
16f10 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
16f20 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
16f30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
16f40 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
16f50 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
16f60 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
16f70 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
16f80 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
16f90 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
16fa0 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
16fb0 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
16fc0 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
16fd0 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
16fe0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
16ff0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
17000 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
17010 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
17020 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
17030 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
17040 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
17050 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
17060 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
17070 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
17080 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
17090 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
170a0 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
170b0 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
170c0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
170d0 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
170e0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
170f0 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
17100 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
17110 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
17120 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
17130 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
17140 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
17150 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
17160 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
17170 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
17180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17190 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
171a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
171b0 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
171c0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
171d0 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
171e0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
171f0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
17200 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
17210 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
17220 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
17230 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
17240 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
17250 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
17260 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
17270 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
17280 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
17290 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
172a0 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
172b0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
172c0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
172d0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
172e0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
172f0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
17300 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
17310 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
17320 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17330 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
17340 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
17350 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
17360 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
17370 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
17380 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
17390 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
173a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
173b0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
173c0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
173d0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
173e0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
173f0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
17400 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
17410 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
17420 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
17430 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
17440 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
17450 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
17460 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
17470 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
17480 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
17490 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
174a0 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
174b0 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
174c0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
174d0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
174e0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
174f0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
17500 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
17510 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
17520 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
17530 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
17540 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17550 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
17560 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
17570 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
17580 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
17590 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
175a0 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
175b0 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
175c0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
175d0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
175e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
175f0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
17600 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17610 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
17620 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
17630 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
17640 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
17650 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
17660 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
17670 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
17680 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
17690 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
176a0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
176b0 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
176c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
176d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
176e0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
176f0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
17700 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
17710 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
17720 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
17730 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
17740 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
17750 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
17760 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
17770 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
17780 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
17790 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
177a0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
177b0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
177c0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
177d0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
177e0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
177f0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
17800 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
17810 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
17820 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
17830 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
17840 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
17850 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
17860 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
17870 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
17880 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
17890 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
178a0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
178b0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
178c0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
178d0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
178e0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
178f0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
17900 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
17910 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
17920 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
17930 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
17940 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
17950 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
17960 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
17970 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
17980 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
17990 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
179a0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
179b0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
179c0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
179d0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
179e0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
179f0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
17a00 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
17a10 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
17a20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
17a30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
17a40 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
17a50 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
17a60 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
17a70 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
17a80 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
17a90 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
17aa0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
17ab0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
17ac0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
17ad0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
17ae0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
17af0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
17b00 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
17b10 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
17b20 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
17b30 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
17b40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17b50 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
17b60 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
17b70 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
17b80 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
17b90 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
17ba0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
17bb0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
17bc0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
17bd0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
17be0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
17bf0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
17c00 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
17c10 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
17c20 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
17c30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
17c40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
17c50 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
17c60 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
17c70 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
17c80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17c90 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
17ca0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
17cb0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
17cc0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
17cd0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
17ce0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
17cf0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17d00 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
17d10 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
17d20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
17d30 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
17d40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
17d50 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
17d60 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
17d70 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
17d80 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
17d90 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
17da0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
17db0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
17dc0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17dd0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
17de0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17df0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
17e00 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17e10 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
17e20 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17e30 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
17e40 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
17e50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
17e60 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
17e70 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
17e80 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
17e90 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
17ea0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
17eb0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
17ec0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
17ed0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17ee0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
17ef0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
17f00 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
17f10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17f20 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
17f30 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
17f40 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
17f50 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
17f60 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
17f70 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
17f80 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
17f90 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
17fa0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
17fb0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
17fc0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
17fd0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
17fe0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
17ff0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
18000 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
18010 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
18020 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
18030 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
18040 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
18050 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
18060 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
18070 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
18080 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
18090 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
180a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
180b0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
180c0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
180d0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
180e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
180f0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
18100 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
18110 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
18120 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
18130 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
18140 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
18150 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
18160 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
18170 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
18180 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
18190 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
181a0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
181b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
181c0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
181d0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
181e0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
181f0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
18200 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
18210 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
18220 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
18230 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
18240 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
18250 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
18260 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
18270 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
18280 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
18290 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
182a0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
182b0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
182c0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
182d0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
182e0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
182f0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
18300 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
18310 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
18320 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
18330 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
18340 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
18350 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
18360 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  rmsg()]..*/.SQLI
18370 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
18380 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
18390 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
183a0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
183b0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
183c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
183d0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
183e0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
183f0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
18400 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
18410 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
18420 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
18430 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
18440 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
18450 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
18460 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
18470 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
18480 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
18490 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
184a0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
184b0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
184c0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
184d0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
184e0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
184f0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
18500 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
18510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18520 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
18530 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
18540 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
18550 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
18560 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
18570 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
18580 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
18590 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
185a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
185b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
185c0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
185d0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
185e0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
185f0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
18600 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
18610 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
18620 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
18630 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
18640 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
18650 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
18660 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
18670 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
18680 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
18690 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
186a0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
186b0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
186c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
186d0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
186e0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
186f0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
18700 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
18710 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
18720 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
18730 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
18740 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
18750 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
18760 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
18770 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
18780 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
18790 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
187a0 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
187b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
187c0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
187d0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
187e0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
187f0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
18800 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
18810 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
18820 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
18830 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
18840 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
18850 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
18860 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
18870 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
18880 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
18890 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
188a0 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
188b0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
188c0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
188d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
188e0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
188f0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
18900 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
18910 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
18920 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
18930 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
18940 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
18950 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
18960 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
18970 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
18980 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
18990 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
189a0 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
189b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
189c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
189d0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
189e0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
189f0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
18a00 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
18a10 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
18a20 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
18a30 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
18a40 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
18a50 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
18a60 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
18a70 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
18a80 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
18a90 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
18aa0 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
18ab0 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
18ac0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
18ad0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
18ae0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
18af0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
18b00 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
18b10 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
18b20 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
18b30 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
18b40 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
18b50 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
18b60 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
18b70 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
18b80 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
18b90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
18ba0 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
18bb0 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
18bc0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
18bd0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
18be0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
18bf0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
18c00 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
18c10 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
18c20 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
18c30 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
18c40 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
18c50 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
18c60 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
18c70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
18c80 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
18c90 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
18ca0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
18cb0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
18cc0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
18cd0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
18ce0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
18cf0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
18d00 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
18d10 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
18d20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
18d30 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
18d40 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
18d50 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
18d60 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
18d70 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
18d80 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
18d90 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
18da0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
18db0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
18dc0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
18dd0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
18de0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
18df0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
18e00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18e10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18e20 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
18e30 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
18e40 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
18e50 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
18e60 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
18e70 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
18e80 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
18e90 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18ea0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
18eb0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
18ec0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
18ed0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
18ee0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
18ef0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
18f00 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
18f10 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
18f20 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
18f30 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
18f40 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
18f50 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
18f60 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
18f70 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
18f80 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
18f90 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
18fa0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
18fb0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
18fc0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
18fd0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
18fe0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
18ff0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
19000 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
19010 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
19020 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
19030 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
19040 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
19050 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
19060 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
19070 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
19080 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
19090 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
190a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
190b0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
190c0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
190d0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
190e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
190f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
19100 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
19110 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
19120 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
19130 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
19140 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
19150 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
19160 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
19170 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
19180 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
19190 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
191a0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
191b0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
191c0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
191d0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
191e0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
191f0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
19200 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
19210 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
19220 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
19230 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
19240 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
19250 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
19260 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
19270 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
19280 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
19290 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
192a0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
192b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
192c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
192d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
192e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
192f0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
19300 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
19310 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
19320 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
19330 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
19340 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
19350 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
19360 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
19370 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
19380 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
19390 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
193a0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
193b0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
193c0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
193d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
193e0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
193f0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
19400 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
19410 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
19420 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
19430 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
19440 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
19450 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
19460 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
19470 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
19480 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
19490 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51   string.)^.*/.SQ
194a0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
194b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
194c0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
194d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
194e0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
194f0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
19500 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45  va_list);.SQLITE
19510 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
19520 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
19530 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
19540 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
19550 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
19560 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
19570 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
19580 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
19590 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
195a0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
195b0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
195c0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
195d0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
195e0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
195f0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
19600 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
19610 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
19620 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
19630 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
19640 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
19650 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
19660 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
19670 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
19680 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
19690 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
196a0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
196b0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
196c0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
196d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
196e0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
196f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
19700 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
19710 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
19720 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
19730 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
19740 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
19750 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
19760 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
19770 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
19780 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
19790 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
197a0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
197b0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
197c0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
197d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
197e0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
197f0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
19800 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
19810 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
19820 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
19830 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
19840 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
19850 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
19860 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
19870 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
19880 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
19890 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
198a0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
198b0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
198c0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
198d0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
198e0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
198f0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
19900 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
19910 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
19920 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
19930 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
19940 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
19950 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
19960 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
19970 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
19980 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
19990 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
199a0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
199b0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
199c0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
199d0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
199e0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
199f0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
19a00 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
19a10 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
19a20 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
19a30 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
19a40 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
19a50 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
19a60 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
19a70 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
19a80 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
19a90 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
19aa0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
19ab0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19ac0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
19ad0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
19ae0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
19af0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
19b00 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
19b10 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
19b20 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
19b30 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
19b40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19b50 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
19b60 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
19b70 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
19b80 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
19b90 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
19ba0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
19bb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
19bc0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
19bd0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
19be0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
19bf0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
19c00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
19c10 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
19c20 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
19c30 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
19c40 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
19c50 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
19c60 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19c70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
19c80 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
19c90 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
19ca0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
19cb0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
19cc0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
19cd0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
19ce0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
19cf0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
19d00 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
19d10 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
19d20 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
19d30 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
19d40 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
19d50 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
19d60 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
19d70 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
19d80 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
19d90 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
19da0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
19db0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19dc0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
19dd0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
19de0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
19df0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
19e00 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
19e10 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
19e20 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
19e30 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
19e40 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
19e50 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
19e60 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
19e70 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
19e80 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
19e90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
19ea0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
19eb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
19ec0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
19ed0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
19ee0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
19ef0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
19f00 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
19f10 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
19f20 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
19f30 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
19f40 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
19f50 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
19f60 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
19f70 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
19f80 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
19f90 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
19fa0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
19fb0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
19fc0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
19fd0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
19fe0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
19ff0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1a000 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1a010 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1a020 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1a030 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1a040 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1a050 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1a060 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1a070 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1a080 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1a090 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1a0a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
1a0b0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1a0c0 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
1a0d0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1a0e0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1a0f0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1a100 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1a110 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1a120 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1a130 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1a140 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1a150 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1a160 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1a170 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1a180 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1a190 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1a1a0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
1a1b0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1a1c0 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
1a1d0 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1a1e0 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1a1f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1a200 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1a210 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1a220 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1a230 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1a240 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1a250 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a260 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1a270 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1a280 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1a290 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1a2a0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1a2b0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1a2c0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1a2d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1a2e0 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1a2f0 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1a300 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1a310 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1a320 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1a330 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1a340 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1a350 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1a360 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1a370 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1a380 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1a390 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1a3a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1a3b0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1a3c0 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1a3d0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1a3e0 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1a3f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1a400 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
1a410 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1a420 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a430 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1a440 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1a450 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1a460 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1a470 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1a480 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1a490 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1a4a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1a4b0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1a4c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1a4d0 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1a4e0 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1a4f0 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1a500 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1a510 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1a520 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1a530 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1a540 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1a550 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1a560 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1a570 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1a580 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1a590 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1a5a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1a5b0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1a5c0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1a5d0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1a5e0 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1a5f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1a600 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1a610 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1a620 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1a630 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1a640 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a650 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a660 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1a670 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a680 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1a690 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1a6a0 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1a6b0 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1a6c0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1a6d0 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1a6e0 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1a6f0 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1a700 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1a710 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1a720 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1a730 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1a740 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1a750 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1a760 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1a770 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1a780 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1a790 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1a7a0 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1a7b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1a7c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1a7d0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1a7e0 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1a7f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a800 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1a810 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1a820 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1a830 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1a840 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1a850 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
1a860 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
1a870 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1a880 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
1a890 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1a8a0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1a8b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1a8c0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1a8d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1a8e0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1a8f0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1a900 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1a910 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1a920 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1a930 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1a940 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1a950 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1a960 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1a970 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1a980 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1a990 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1a9a0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1a9b0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1a9c0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1a9d0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1a9e0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1a9f0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1aa00 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1aa10 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1aa20 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1aa30 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1aa40 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1aa50 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1aa60 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1aa70 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1aa80 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1aa90 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1aaa0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1aab0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1aac0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
1aad0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
1aae0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
1aaf0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
1ab00 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
1ab10 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
1ab20 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
1ab30 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1ab40 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
1ab50 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
1ab60 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
1ab70 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1ab80 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
1ab90 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
1aba0 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
1abb0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
1abc0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
1abd0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
1abe0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
1abf0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
1ac00 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
1ac10 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
1ac20 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1ac30 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1ac40 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1ac50 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1ac60 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1ac70 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1ac80 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
1ac90 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1aca0 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
1acb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1acc0 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
1acd0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1ace0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
1acf0 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
1ad00 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
1ad10 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
1ad20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ad30 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
1ad40 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
1ad50 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
1ad60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1ad70 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1ad80 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
1ad90 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
1ada0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1adb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1adc0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1add0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
1ade0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
1adf0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
1ae00 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
1ae10 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
1ae20 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
1ae30 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
1ae40 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
1ae50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1ae60 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
1ae70 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
1ae80 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
1ae90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1aea0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
1aeb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1aec0 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
1aed0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
1aee0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
1aef0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
1af00 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
1af10 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
1af20 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
1af30 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
1af40 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
1af50 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
1af60 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
1af70 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
1af80 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
1af90 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
1afa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1afb0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
1afc0 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
1afd0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1afe0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
1aff0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
1b000 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
1b010 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
1b020 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
1b030 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
1b040 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
1b050 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
1b060 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
1b070 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
1b080 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
1b090 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1b0a0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
1b0b0 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
1b0c0 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
1b0d0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
1b0e0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1b0f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
1b100 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
1b110 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b120 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
1b130 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
1b140 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
1b150 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
1b160 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
1b170 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
1b180 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
1b190 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
1b1a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
1b1b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
1b1c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1b1d0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
1b1e0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
1b1f0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
1b200 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b210 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
1b220 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
1b230 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
1b240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1b250 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
1b260 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
1b270 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
1b280 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
1b290 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
1b2a0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
1b2b0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
1b2c0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
1b2d0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
1b2e0 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
1b2f0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1b300 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
1b310 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
1b320 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
1b330 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1b340 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
1b350 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1b360 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
1b370 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
1b380 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1b390 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
1b3a0 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
1b3b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
1b3c0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
1b3d0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
1b3e0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
1b3f0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
1b400 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
1b410 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
1b420 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
1b430 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
1b440 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
1b450 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
1b460 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
1b470 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1b480 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
1b490 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
1b4a0 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
1b4b0 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
1b4c0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
1b4d0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1b4e0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
1b4f0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b500 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
1b510 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
1b520 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
1b530 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
1b540 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
1b550 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
1b560 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
1b570 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
1b580 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
1b590 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
1b5a0 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
1b5b0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
1b5c0 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
1b5d0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
1b5e0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
1b5f0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
1b600 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
1b610 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1b620 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
1b630 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
1b640 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
1b650 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
1b660 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
1b670 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
1b680 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
1b690 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
1b6a0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
1b6b0 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
1b6c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1b6d0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
1b6e0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
1b6f0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
1b700 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
1b710 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
1b720 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
1b730 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
1b740 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
1b750 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
1b760 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
1b770 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
1b780 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
1b790 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
1b7a0 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
1b7b0 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
1b7c0 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
1b7d0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
1b7e0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
1b7f0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
1b800 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
1b810 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
1b820 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
1b830 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
1b840 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
1b850 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
1b860 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
1b870 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
1b880 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
1b890 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
1b8a0 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
1b8b0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
1b8c0 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
1b8d0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
1b8e0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
1b8f0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
1b900 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
1b910 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
1b920 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
1b930 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
1b940 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
1b950 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
1b960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1b970 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
1b980 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
1b990 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1b9a0 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
1b9b0 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
1b9c0 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
1b9d0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
1b9e0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
1b9f0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
1ba00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
1ba10 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
1ba20 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
1ba30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ba40 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1ba50 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1ba60 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1ba70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ba80 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1ba90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1baa0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
1bab0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1bac0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1bad0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1bae0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1baf0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1bb00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1bb10 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1bb20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1bb30 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1bb40 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
1bb50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
1bb60 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
1bb70 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
1bb80 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
1bb90 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
1bba0 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
1bbb0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
1bbc0 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
1bbd0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
1bbe0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1bbf0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
1bc00 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
1bc10 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
1bc20 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
1bc30 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
1bc40 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1bc50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
1bc60 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1bc70 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1bc80 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
1bc90 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
1bca0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1bcb0 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
1bcc0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
1bcd0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
1bce0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
1bcf0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
1bd00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
1bd10 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
1bd20 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
1bd30 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
1bd40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
1bd50 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
1bd60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
1bd70 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
1bd80 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
1bd90 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
1bda0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1bdb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1bdc0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
1bdd0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
1bde0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
1bdf0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1be00 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1be10 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
1be20 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
1be30 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
1be40 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
1be50 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
1be60 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
1be70 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1be80 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
1be90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
1bea0 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
1beb0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
1bec0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
1bed0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
1bee0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
1bef0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
1bf00 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1bf10 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
1bf20 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
1bf30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1bf40 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1bf50 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
1bf60 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
1bf70 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1bf80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
1bf90 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
1bfa0 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
1bfb0 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
1bfc0 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
1bfd0 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
1bfe0 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1bff0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1c000 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1c010 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1c020 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1c030 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1c040 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1c050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c060 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1c070 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1c080 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1c090 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1c0a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c0b0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1c0c0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1c0d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1c0e0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1c0f0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1c100 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1c110 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1c120 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1c130 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1c140 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1c150 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1c160 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1c170 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1c180 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1c190 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1c1a0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1c1b0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1c1c0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1c1d0 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1c1e0 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1c1f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c200 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1c210 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1c220 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1c230 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1c240 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1c250 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1c260 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1c270 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1c280 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1c290 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1c2a0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1c2b0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1c2c0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1c2d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1c2e0 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1c2f0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1c300 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1c310 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1c320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1c330 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1c340 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1c350 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1c360 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1c370 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1c380 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1c390 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1c3a0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1c3b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1c3c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1c3d0 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
1c3e0 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
1c3f0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
1c400 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
1c410 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
1c420 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
1c430 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
1c440 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
1c450 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
1c460 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
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 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
1c4a0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
1c4b0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
1c4c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
1c4d0 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
1c4e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1c4f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1c500 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c510 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
1c520 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
1c530 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c540 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1c550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c560 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
1c570 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
1c580 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1c590 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c5a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c5b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
1c5c0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
1c5d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1c5e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1c5f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c600 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
1c610 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
1c620 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1c630 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1c640 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c650 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
1c660 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
1c670 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1c680 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1c690 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1c6a0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
1c6b0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
1c6c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1c6d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1c6e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1c6f0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
1c700 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
1c710 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1c720 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1c730 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
1c740 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
1c750 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
1c760 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1c770 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c780 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1c790 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
1c7a0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
1c7b0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1c7c0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1c7d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1c7e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
1c7f0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
1c800 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1c810 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1c820 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1c830 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
1c840 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
1c850 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1c860 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1c870 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1c880 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
1c890 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1c8a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c8b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c8c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1c8d0 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
1c8e0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1c8f0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1c900 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c910 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1c920 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
1c930 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1c940 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1c950 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c960 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
1c970 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
1c980 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1c990 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1c9a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c9b0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
1c9c0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
1c9d0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1c9e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c9f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ca00 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
1ca10 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
1ca20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ca30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ca40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ca50 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
1ca60 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
1ca70 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
1ca80 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
1ca90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1caa0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
1cab0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
1cac0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
1cad0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
1cae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1caf0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
1cb00 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
1cb10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
1cb20 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1cb30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cb40 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
1cb50 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
1cb60 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
1cb70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1cb80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
1cb90 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
1cba0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
1cbb0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
1cbc0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
1cbd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
1cbe0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1cbf0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
1cc00 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
1cc10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1cc20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
1cc30 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
1cc40 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
1cc50 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
1cc60 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1cc70 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
1cc80 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
1cc90 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
1cca0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
1ccb0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ccc0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
1ccd0 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
1cce0 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
1ccf0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1cd00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1cd10 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
1cd20 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
1cd30 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1cd40 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1cd50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1cd60 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1cd70 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
1cd80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1cd90 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1cda0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1cdb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
1cdc0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
1cdd0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1cde0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
1cdf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ce00 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
1ce10 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
1ce20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1ce30 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
1ce40 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
1ce50 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
1ce60 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
1ce70 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1ce80 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
1ce90 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
1cea0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
1ceb0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
1cec0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
1ced0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
1cee0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
1cef0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
1cf00 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
1cf10 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
1cf20 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1cf30 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
1cf40 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
1cf50 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
1cf60 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
1cf70 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
1cf80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1cf90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1cfa0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
1cfb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1cfc0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
1cfd0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
1cfe0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
1cff0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
1d000 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
1d010 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
1d020 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
1d030 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d040 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
1d050 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
1d060 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1d070 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
1d080 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
1d090 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
1d0a0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
1d0b0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1d0c0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
1d0d0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
1d0e0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
1d0f0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
1d100 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
1d110 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
1d120 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
1d130 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
1d140 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
1d150 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
1d160 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1d170 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1d180 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
1d190 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
1d1a0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
1d1b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
1d1c0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
1d1d0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
1d1e0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
1d1f0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
1d200 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
1d210 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
1d220 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
1d230 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
1d240 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
1d250 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
1d260 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
1d270 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
1d280 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
1d290 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
1d2a0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
1d2b0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
1d2c0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
1d2d0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
1d2e0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
1d2f0 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
1d300 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
1d310 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
1d320 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
1d330 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
1d340 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
1d350 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
1d360 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
1d370 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
1d380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
1d390 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
1d3a0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
1d3b0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
1d3c0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
1d3d0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
1d3e0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1d3f0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
1d400 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
1d410 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
1d420 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
1d430 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
1d440 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
1d450 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
1d460 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1d470 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1d480 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1d490 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1d4a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1d4b0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1d4c0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1d4d0 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1d4e0 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1d4f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d500 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1d510 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1d520 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1d530 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1d540 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1d550 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1d560 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1d570 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1d580 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
1d590 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
1d5a0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
1d5b0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d5c0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
1d5d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
1d5e0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
1d5f0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
1d600 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
1d610 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
1d620 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
1d630 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
1d640 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
1d650 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
1d660 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1d670 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
1d680 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1d690 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
1d6a0 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
1d6b0 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
1d6c0 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
1d6d0 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
1d6e0 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
1d6f0 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
1d700 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
1d710 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
1d720 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
1d730 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
1d740 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
1d750 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
1d760 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
1d770 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
1d780 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
1d790 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1d7a0 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
1d7b0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
1d7c0 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
1d7d0 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
1d7e0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
1d7f0 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
1d800 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
1d810 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
1d820 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
1d830 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
1d840 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
1d850 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
1d860 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1d870 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
1d880 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
1d890 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
1d8a0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
1d8b0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1d8c0 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
1d8d0 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
1d8e0 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
1d8f0 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
1d900 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
1d910 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
1d920 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
1d930 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
1d940 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1d950 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1d960 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
1d970 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
1d980 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
1d990 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d9a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
1d9b0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
1d9c0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
1d9d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
1d9e0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
1d9f0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
1da00 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
1da10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1da20 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
1da30 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
1da40 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
1da50 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
1da60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1da70 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
1da80 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
1da90 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
1daa0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
1dab0 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
1dac0 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
1dad0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1dae0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1daf0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1db00 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1db10 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1db20 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1db30 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1db40 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1db50 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1db60 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1db70 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1db80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1db90 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1dba0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1dbb0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1dbc0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1dbd0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1dbe0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1dbf0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1dc00 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1dc10 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1dc20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1dc30 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1dc40 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1dc50 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1dc60 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1dc70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1dc80 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1dc90 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1dca0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1dcb0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1dcc0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1dcd0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1dce0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1dcf0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1dd00 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1dd10 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1dd20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1dd30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1dd40 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1dd50 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1dd60 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1dd70 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1dd80 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1dd90 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1dda0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1ddb0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1ddc0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1ddd0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1dde0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1ddf0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1de00 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1de10 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1de20 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1de30 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1de40 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1de50 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1de60 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1de70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1de80 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1de90 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1dea0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1deb0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1dec0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1ded0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1dee0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1def0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1df00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1df10 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1df20 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1df30 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1df40 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1df50 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1df60 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1df70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1df80 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1df90 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1dfa0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1dfb0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1dfc0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1dfd0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1dfe0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1dff0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1e000 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1e010 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1e020 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1e030 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1e040 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1e050 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1e060 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1e070 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1e080 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1e090 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1e0a0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1e0b0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1e0c0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1e0d0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1e0e0 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
1e0f0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
1e100 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
1e110 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
1e120 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1e130 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1e140 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1e150 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1e160 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e170 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1e180 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1e190 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1e1a0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1e1b0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1e1c0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1e1d0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1e1e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1e1f0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1e200 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e210 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e220 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1e230 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1e240 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1e250 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1e260 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1e270 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1e280 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1e290 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1e2a0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1e2b0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1e2c0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1e2d0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1e2e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1e2f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e300 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1e310 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1e320 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1e330 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1e340 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1e350 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1e360 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
1e370 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1e380 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1e390 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1e3a0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1e3b0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1e3c0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1e3d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1e3e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1e3f0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1e400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1e410 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1e420 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1e430 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1e440 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
1e450 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1e460 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
1e470 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1e480 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
1e490 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
1e4a0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1e4b0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
1e4c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
1e4d0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1e4e0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
1e4f0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1e500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e510 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
1e520 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
1e530 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
1e540 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
1e550 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
1e560 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
1e570 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
1e580 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
1e590 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
1e5a0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
1e5b0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
1e5c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
1e5d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
1e5e0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
1e5f0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
1e600 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
1e610 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
1e620 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
1e630 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
1e640 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
1e650 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
1e660 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
1e670 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
1e680 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
1e690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
1e6a0 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
1e6b0 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
1e6c0 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
1e6d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1e6e0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
1e6f0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
1e700 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
1e710 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
1e720 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
1e730 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
1e740 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1e750 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
1e760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e770 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
1e780 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
1e790 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
1e7a0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
1e7b0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
1e7c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1e7d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
1e7e0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
1e7f0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
1e800 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1e810 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
1e820 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1e830 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1e840 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
1e850 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e860 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
1e870 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
1e880 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
1e890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1e8a0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
1e8b0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1e8c0 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
1e8d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
1e8e0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
1e8f0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
1e900 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
1e910 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
1e920 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
1e930 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
1e940 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
1e950 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
1e960 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
1e970 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1e980 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1e990 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
1e9a0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1e9b0 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
1e9c0 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
1e9d0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
1e9e0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
1e9f0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
1ea00 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
1ea10 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
1ea20 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
1ea30 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
1ea40 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
1ea50 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
1ea60 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
1ea70 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
1ea80 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
1ea90 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
1eaa0 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
1eab0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
1eac0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
1ead0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1eae0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1eaf0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
1eb00 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
1eb10 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
1eb20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
1eb30 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
1eb40 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1eb50 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
1eb60 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
1eb70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
1eb80 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
1eb90 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
1eba0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
1ebb0 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
1ebc0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
1ebd0 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
1ebe0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1ebf0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
1ec00 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
1ec10 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
1ec20 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
1ec30 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
1ec40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1ec50 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
1ec60 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
1ec70 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
1ec80 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
1ec90 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1eca0 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
1ecb0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1ecc0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
1ecd0 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
1ece0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
1ecf0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
1ed00 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
1ed10 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
1ed20 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
1ed30 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
1ed40 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
1ed50 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
1ed60 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
1ed70 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
1ed80 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
1ed90 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
1eda0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1edb0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
1edc0 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
1edd0 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
1ede0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
1edf0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
1ee00 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
1ee10 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
1ee20 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
1ee30 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
1ee40 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1ee50 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1ee60 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
1ee70 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
1ee80 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
1ee90 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
1eea0 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
1eeb0 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
1eec0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1eed0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1eee0 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
1eef0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
1ef00 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
1ef10 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
1ef20 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
1ef30 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
1ef40 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1ef50 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
1ef60 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
1ef70 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
1ef80 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
1ef90 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
1efa0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
1efb0 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
1efc0 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
1efd0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1efe0 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
1eff0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
1f000 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
1f010 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
1f020 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
1f030 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
1f040 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1f050 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
1f060 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
1f070 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
1f080 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
1f090 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
1f0a0 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
1f0b0 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
1f0c0 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
1f0d0 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
1f0e0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
1f0f0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
1f100 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
1f110 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
1f120 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
1f130 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
1f140 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
1f150 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
1f160 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
1f170 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
1f180 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
1f190 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
1f1a0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
1f1b0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
1f1c0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
1f1d0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
1f1e0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
1f1f0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
1f200 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
1f210 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
1f220 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
1f230 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
1f240 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
1f250 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
1f260 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
1f270 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
1f280 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
1f290 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
1f2a0 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
1f2b0 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
1f2c0 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
1f2d0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1f2e0 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1f2f0 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
1f300 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
1f310 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1f320 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
1f330 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
1f340 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
1f350 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
1f360 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
1f370 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
1f380 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
1f390 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
1f3a0 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
1f3b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
1f3c0 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
1f3d0 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
1f3e0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
1f3f0 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
1f400 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
1f410 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
1f420 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
1f430 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
1f440 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
1f450 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1f460 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1f470 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
1f480 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
1f490 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
1f4a0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
1f4b0 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
1f4c0 22 72 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  "rw" or.**     "
1f4d0 72 77 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  rwc". Attempting
1f4e0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
1f4f0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
1f500 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
1f510 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
1f520 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
1f530 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
1f540 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
1f550 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
1f560 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
1f570 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
1f580 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
1f590 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
1f5a0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
1f5b0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1f5c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f5d0 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
1f5e0 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
1f5f0 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
1f600 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1f610 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1f620 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
1f630 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
1f640 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
1f650 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
1f660 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
1f670 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
1f680 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
1f690 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
1f6a0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
1f6b0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
1f6c0 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
1f6d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1f6e0 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
1f6f0 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66  OPEN_CREATE. ^If
1f700 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1f710 28 29 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73  () is .**     us
1f720 65 64 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72  ed, it is an err
1f730 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
1f740 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f  value for the mo
1f750 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
1f760 74 20 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73  t is .**     les
1f770 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
1f780 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
1f790 64 20 62 79 20 74 68 65 20 66 6c 61 67 73 20 70  d by the flags p
1f7a0 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69  assed as the thi
1f7b0 72 64 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  rd .**     param
1f7c0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  eter..**.**   <l
1f7d0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
1f7e0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
1f7f0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
1f800 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
1f810 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
1f820 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
1f830 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
1f840 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
1f850 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
1f860 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
1f870 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
1f880 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
1f890 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
1f8a0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
1f8b0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
1f8c0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
1f8d0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
1f8e0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
1f8f0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
1f900 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
1f910 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1f920 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
1f930 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1f940 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1f950 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
1f960 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
1f970 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
1f980 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
1f990 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
1f9a0 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65  any behaviour re
1f9b0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
1f9c0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
1f9d0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
1f9e0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
1f9f0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
1fa00 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  ag..** </ul>.**.
1fa10 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  ** ^Specifying a
1fa20 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65  n unknown parame
1fa30 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79  ter in the query
1fa40 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1fa50 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a  URI is not an.**
1fa60 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20   error.  Future 
1fa70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1fa80 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74  te might underst
1fa90 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71  and additional q
1faa0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
1fab0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79  rs.  See "[query
1fac0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68   parameters with
1fad0 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67   special meaning
1fae0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72   to SQLite]" for
1faf0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
1fb00 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1fb10 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
1fb20 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e   examples]] <h3>
1fb30 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1fb40 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  mples</h3>.**.**
1fb50 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
1fb60 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20  1" align=center 
1fb70 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a  cellpadding=5>.*
1fb80 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66  * <tr><th> URI f
1fb90 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65  ilenames <th> Re
1fba0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64  sults.** <tr><td
1fbb0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c  > file:data.db <
1fbc0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1fbd0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
1fbe0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
1fbf0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
1fc00 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  y..** <tr><td> f
1fc10 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
1fc20 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20  ata.db<br>.**   
1fc30 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68         file:///h
1fc40 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
1fc50 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <br> .**       
1fc60 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68     file://localh
1fc70 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  ost/home/fred/da
1fc80 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20  ta.db <br> <td> 
1fc90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1fca0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1fcb0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
1fcc0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72  data.db"..** <tr
1fcd0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72  ><td> file://dar
1fce0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f  kstar/home/fred/
1fcf0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
1fd00 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
1fd10 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69  or. "darkstar" i
1fd20 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a  s not a recogniz
1fd30 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a  ed authority..**
1fd40 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22   <tr><td style="
1fd50 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72  white-space:nowr
1fd60 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  ap"> .**        
1fd70 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63    file:///C:/Doc
1fd80 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53  uments%20and%20S
1fd90 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73  ettings/fred/Des
1fda0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20  ktop/data.db.** 
1fdb0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73      <td> Windows
1fdc0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20   only: Open the 
1fdd0 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f  file "data.db" o
1fde0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70  n fred's desktop
1fdf0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20   on drive.**    
1fe00 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74        C:. Note t
1fe10 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61  hat the %20 esca
1fe20 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61  ping in this exa
1fe30 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69  mple is not stri
1fe40 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20  ctly .**        
1fe50 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70    necessary - sp
1fe60 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63  ace characters c
1fe70 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72  an be used liter
1fe80 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  ally.**         
1fe90 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65   in URI filename
1fea0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  s..** <tr><td> f
1feb0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
1fec0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74  =ro&cache=privat
1fed0 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  e <td> .**      
1fee0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64      Open file "d
1fef0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
1ff00 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
1ff10 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61   for read-only a
1ff20 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20  ccess..**       
1ff30 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66     Regardless of
1ff40 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ff50 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64  shared-cache mod
1ff60 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a  e is enabled by.
1ff70 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61  **          defa
1ff80 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61  ult, use a priva
1ff90 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72  te cache..** <tr
1ffa0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1ffb0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66  /fred/data.db?vf
1ffc0 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74  s=unix-nolock <t
1ffd0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
1ffe0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
1fff0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
20000 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
20010 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22  FS "unix-nolock"
20020 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20030 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
20040 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
20050 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
20060 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
20070 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
20080 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
20090 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
200a0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
200b0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
200c0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
200d0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
200e0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
200f0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
20100 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
20110 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
20120 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20130 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
20140 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
20150 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
20160 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
20170 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
20180 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
20190 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
201a0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
201b0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
201c0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
201d0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
201e0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
201f0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
20200 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
20210 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
20220 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
20230 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
20240 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
20250 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
20260 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
20270 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
20280 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
20290 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
202a0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
202b0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
202c0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
202d0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
202e0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
202f0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
20300 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
20310 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
20320 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
20330 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
20340 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
20350 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
20360 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
20370 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
20380 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
20390 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
203a0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
203b0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
203c0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
203d0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
203e0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
203f0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
20400 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
20410 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45  _v2()..*/.SQLITE
20420 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
20430 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
20440 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
20450 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
20460 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
20470 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
20480 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
20490 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
204a0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
204b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
204c0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
204d0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
204e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
204f0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
20500 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
20510 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
20520 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
20530 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c  handle */.);.SQL
20540 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
20550 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
20560 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
20570 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
20580 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
20590 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
205a0 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
205b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
205c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
205d0 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
205e0 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
205f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
20600 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
20610 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
20620 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
20630 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20640 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
20650 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
20660 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
20670 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
20680 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
20690 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
206a0 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
206b0 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
206c0 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
206d0 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
206e0 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
206f0 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
20700 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
20710 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
20720 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
20730 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
20740 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
20750 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
20760 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
20770 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
20780 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
20790 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
207a0 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
207b0 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
207c0 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
207d0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
207e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
207f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
20800 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
20810 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
20820 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
20830 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
20840 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
20850 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
20860 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
20870 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
20880 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
20890 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
208a0 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
208b0 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
208c0 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
208d0 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
208e0 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
208f0 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
20900 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
20910 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
20920 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
20930 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
20940 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
20950 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
20960 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
20970 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
20980 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
20990 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
209a0 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
209b0 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
209c0 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
209d0 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
209e0 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
209f0 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
20a00 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
20a10 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
20a20 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
20a30 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
20a40 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
20a50 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
20a60 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
20a70 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
20a80 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
20a90 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
20aa0 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
20ab0 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
20ac0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20ad0 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
20ae0 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
20af0 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
20b00 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
20b10 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
20b20 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
20b30 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
20b40 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
20b50 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
20b60 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
20b70 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
20b80 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
20b90 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
20ba0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
20bb0 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
20bc0 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
20bd0 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
20be0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
20bf0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
20c00 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
20c10 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
20c20 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
20c30 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
20c40 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
20c50 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
20c60 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
20c70 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
20c80 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
20c90 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
20ca0 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
20cb0 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
20cc0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
20cd0 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
20ce0 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
20cf0 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
20d00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
20d10 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
20d20 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
20d30 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
20d40 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
20d50 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
20d60 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
20d70 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
20d80 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
20d90 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
20da0 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
20db0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
20dc0 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
20dd0 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
20de0 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
20df0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
20e00 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
20e10 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
20e20 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
20e30 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  able..*/.SQLITE_
20e40 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
20e50 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
20e60 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
20e70 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
20e80 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
20e90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
20ea0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20eb0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
20ec0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
20ed0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
20ee0 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54  bDefault);.SQLIT
20ef0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
20f00 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  t64 sqlite3_uri_
20f10 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72  int64(const char
20f20 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
20f30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
20f40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20f50 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e  : Error Codes An
20f60 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a  d Messages.**.**
20f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
20f80 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63  rcode() interfac
20f90 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
20fa0 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
20fb0 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
20fc0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
20fd0 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65   for the most re
20fe0 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69  cent failed sqli
20ff0 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a  te3_* API call.*
21000 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
21010 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
21020 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20  nnection]. If a 
21030 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66  prior API call f
21040 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65  ailed.** but the
21050 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
21060 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c   call succeeded,
21070 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
21080 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  e from.** sqlite
21090 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20 75  3_errcode() is u
210a0 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  ndefined.  ^The 
210b0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
210c0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
210d0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
210e0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
210f0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
21100 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
21110 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
21120 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
21130 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
21140 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
21150 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
21160 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
21170 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
21180 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
21190 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
211a0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
211b0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
211c0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
211d0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
211e0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
211f0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
21200 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
21210 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
21220 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
21230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
21240 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
21250 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
21260 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
21270 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
21280 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
21290 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
212a0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
212b0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
212c0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
212d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
212e0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
212f0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
21300 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
21310 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
21320 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
21330 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
21340 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
21350 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
21360 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
21370 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
21380 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
21390 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
213a0 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
213b0 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
213c0 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
213d0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
213e0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
213f0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
21400 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
21410 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
21420 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
21430 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
21440 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
21450 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
21460 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
21470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21480 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
21490 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
214a0 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
214b0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
214c0 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
214d0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
214e0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
214f0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
21500 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
21510 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
21520 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
21530 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
21540 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
21550 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
21560 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
21570 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
21580 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
21590 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
215a0 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
215b0 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
215c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
215d0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
215e0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
215f0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
21600 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
21610 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
21620 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
21630 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
21640 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
21650 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
21660 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
21670 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
21680 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
21690 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
216a0 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
216b0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
216c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
216d0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
216e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
216f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
21700 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
21710 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
21720 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
21730 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
21740 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
21750 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
21760 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
21770 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
21780 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
21790 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
217a0 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
217b0 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
217c0 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
217d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
217e0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
217f0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
21800 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
21810 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
21820 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
21830 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
21840 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
21850 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
21860 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
21870 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
21880 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
21890 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
218a0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
218b0 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
218c0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
218d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
218e0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
218f0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
21900 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
21910 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21920 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
21930 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
21940 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
21950 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
21960 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
21970 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
21980 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
21990 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
219a0 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
219b0 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
219c0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
219d0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
219e0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
219f0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
21a00 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
21a10 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
21a20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
21a30 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
21a40 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
21a50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
21a60 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
21a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
21a80 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
21a90 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
21aa0 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
21ab0 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
21ac0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
21ad0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
21ae0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
21af0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
21b00 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
21b10 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
21b20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21b30 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
21b40 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
21b50 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
21b60 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
21b70 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
21b80 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
21b90 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
21ba0 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
21bb0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
21bc0 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
21bd0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
21be0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
21bf0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
21c00 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
21c10 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
21c20 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
21c30 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
21c40 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
21c50 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
21c60 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
21c70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
21c80 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
21c90 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
21ca0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
21cb0 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
21cc0 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
21cd0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
21ce0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
21cf0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
21d00 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
21d10 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
21d20 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
21d30 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
21d40 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
21d50 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
21d60 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
21d70 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
21d80 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
21d90 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
21da0 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
21db0 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
21dc0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
21dd0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
21de0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
21df0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
21e00 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
21e10 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
21e20 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
21e30 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
21e40 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
21e50 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
21e60 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
21e70 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
21e80 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
21e90 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
21ea0 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
21eb0 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
21ec0 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
21ed0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
21ee0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
21ef0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
21f00 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
21f10 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
21f20 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
21f30 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
21f40 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
21f50 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
21f60 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
21f70 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
21f80 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
21f90 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
21fa0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
21fb0 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
21fc0 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
21fd0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
21fe0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
21ff0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
22000 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
22010 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
22020 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
22030 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
22040 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
22050 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
22060 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
22070 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
22080 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
22090 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
220a0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
220b0 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
220c0 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
220d0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
220e0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
220f0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
22100 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
22110 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
22120 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22130 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
22140 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
22150 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
22160 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
22170 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
22180 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
22190 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
221a0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
221b0 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
221c0 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
221d0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
221e0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
221f0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
22200 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
22210 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
22220 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
22230 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22240 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
22250 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
22260 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
22270 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
22280 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
22290 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
222a0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
222b0 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
222c0 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
222d0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
222e0 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
222f0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
22300 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
22310 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
22320 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
22330 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
22340 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
22350 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
22360 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
22370 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
22380 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
22390 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
223a0 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
223b0 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
223c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
223d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
223e0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
223f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
22400 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
22410 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
22420 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
22430 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
22440 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
22450 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
22460 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22470 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
22480 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
22490 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
224a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
224b0 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
224c0 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
224d0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
224e0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
224f0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
22500 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
22510 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
22520 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22530 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
22540 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
22550 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
22560 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
22570 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
22580 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22590 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
225a0 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
225b0 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
225c0 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
225d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
225e0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
225f0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
22600 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
22610 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
22620 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
22630 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
22640 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
22650 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
22660 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
22670 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
22680 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
22690 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
226a0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
226b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
226c0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
226d0 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
226e0 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
226f0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22700 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
22710 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
22720 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
22730 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
22740 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
22750 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
22760 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
22770 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
22780 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
22790 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
227a0 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
227b0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
227c0 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
227d0 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
227e0 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
227f0 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
22800 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
22810 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
22820 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
22830 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e  ION_ARG]] ^(<dt>
22840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
22850 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
22860 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
22870 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
22880 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
22890 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
228a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
228b0 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64  _ATTACHED]] ^(<d
228c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
228d0 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
228e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
228f0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
22900 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
22910 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
22920 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
22930 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
22940 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28  N_LENGTH]].** ^(
22950 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
22960 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
22970 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
22980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
22990 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
229a0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
229b0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
229c0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
229d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
229e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
229f0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a  RIABLE_NUMBER]].
22a00 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
22a10 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
22a20 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
22a30 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e  d>The maximum in
22a40 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e  dex number of an
22a50 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  y [parameter] in
22a60 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22a70 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  t.)^.**.** [[SQL
22a80 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
22a90 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
22aa0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
22ab0 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
22ac0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
22ad0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
22ae0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
22af0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
22b00 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
22b10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
22b20 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
22b30 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
22b40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
22b50 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
22b60 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
22b70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
22b80 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
22b90 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
22ba0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
22bb0 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
22bc0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
22bd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
22be0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
22bf0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
22c00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22c10 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
22c20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
22c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22c40 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
22c50 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
22c60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22c70 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
22c80 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
22c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22ca0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
22cb0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
22cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
22cd0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
22ce0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
22cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d00 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
22d10 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
22d20 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
22d30 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
22d40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
22d50 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
22d60 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
22d70 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
22d80 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
22d90 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
22da0 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
22db0 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
22dc0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
22dd0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
22de0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
22df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
22e00 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
22e10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22e20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
22e30 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
22e40 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
22e50 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
22e60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22e70 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22e80 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
22e90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22ea0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
22eb0 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
22ec0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
22ed0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
22ee0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
22ef0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
22f00 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
22f10 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
22f20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
22f30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22f40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
22f50 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
22f60 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
22f70 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
22f80 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
22f90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22fa0 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
22fb0 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
22fc0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
22fd0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
22fe0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
22ff0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
23000 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
23010 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
23020 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
23030 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
23040 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
23050 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
23060 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
23070 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
23080 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
23090 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
230a0 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
230b0 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
230c0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
230d0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
230e0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
230f0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
23100 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
23110 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
23120 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
23130 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
23140 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
23150 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
23160 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
23170 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
23180 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
23190 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
231a0 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
231b0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
231c0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
231d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
231e0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
231f0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
23200 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61  rminator bytes a
23210 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51 4c  s this saves SQL
23220 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20  ite from having 
23230 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70  to.** make a cop
23240 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73  y of the input s
23250 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tring..**.** ^If
23260 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
23270 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
23280 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
23290 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
232a0 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
232b0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
232c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
232d0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
232e0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
232f0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
23300 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
23310 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
23320 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
23330 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
23340 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
23350 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
23360 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
23370 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
23380 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23390 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
233a0 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
233b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
233c0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
233d0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
233e0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
233f0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
23400 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
23410 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
23420 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
23430 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
23440 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
23450 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
23460 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
23470 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
23480 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
23490 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
234a0 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
234b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
234c0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
234d0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
234e0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
234f0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
23500 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
23510 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
23520 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
23530 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
23540 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
23550 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
23560 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
23570 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
23580 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
23590 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
235a0 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
235b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
235c0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
235d0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
235e0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
235f0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
23600 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
23610 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
23620 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
23630 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
23640 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
23650 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
23660 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
23670 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
23680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
23690 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
236a0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
236b0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
236c0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
236d0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
236e0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
236f0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
23700 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
23710 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
23720 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
23730 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
23740 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
23750 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
23760 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
23770 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
23780 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
23790 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
237a0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
237b0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
237c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
237d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
237e0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
237f0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
23800 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
23810 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  in..** </li>.**.
23820 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
23830 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
23840 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23850 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
23860 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
23870 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
23880 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
23890 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
238a0 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
238b0 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
238c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
238d0 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
238e0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
238f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
23900 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
23910 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
23920 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
23930 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
23940 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
23950 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
23960 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
23970 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
23980 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
23990 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
239a0 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
239b0 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
239c0 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
239d0 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
239e0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
239f0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
23a00 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
23a10 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
23a20 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
23a30 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
23a40 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
23a50 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
23a60 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
23a70 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
23a80 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
23a90 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
23aa0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
23ab0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
23ac0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
23ad0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
23ae0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
23af0 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
23b00 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
23b10 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
23b20 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
23b30 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
23b40 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
23b50 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
23b60 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
23b70 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
23b80 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
23b90 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
23ba0 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
23bb0 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
23bc0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
23bd0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
23be0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
23bf0 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
23c00 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
23c10 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
23c20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
23c30 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
23c40 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
23c50 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
23c60 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
23c70 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
23c80 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
23c90 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e  ** the .** </li>
23ca0 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ol>.*/.SQL
23cb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
23cc0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
23cd0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
23ce0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
23cf0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
23d00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
23d10 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
23d20 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
23d30 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
23d40 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
23d50 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
23d60 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
23d70 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
23d80 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
23d90 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
23da0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
23db0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
23dc0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
23dd0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
23de0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
23df0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
23e00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
23e10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
23e20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
23e30 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
23e40 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
23e50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
23e60 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
23e70 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
23e80 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
23e90 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
23ea0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
23eb0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
23ec0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
23ed0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
23ee0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
23ef0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
23f00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
23f10 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
23f20 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
23f30 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
23f40 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
23f50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
23f60 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
23f70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
23f80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
23f90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
23fa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
23fb0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
23fc0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
23fd0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
23fe0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
23ff0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
24000 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
24010 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
24020 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
24030 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
24040 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
24050 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
24060 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
24070 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
24080 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
24090 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
240a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
240b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
240c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
240d0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
240e0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
240f0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
24100 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
24110 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
24120 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
24130 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
24140 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
24150 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
24160 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
24170 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
24180 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
24190 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
241a0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
241b0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
241c0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
241d0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
241e0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
241f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24200 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
24210 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
24220 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
24230 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
24240 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
24250 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
24260 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
24270 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
24280 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
24290 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
242a0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
242b0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
242c0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
242d0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
242e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
242f0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51  e16_v2()]..*/.SQ
24300 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
24310 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
24320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
24330 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
24340 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
24350 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
24360 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
24370 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20   Database.**.** 
24380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
24390 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e  t_readonly(X) in
243a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
243b0 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
243c0 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69  if.** and only i
243d0 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  f the [prepared 
243e0 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b  statement] X mak
243f0 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61  es no direct cha
24400 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63  nges to.** the c
24410 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
24420 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
24430 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70  ** Note that [ap
24440 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
24450 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
24460 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20   or.** [virtual 
24470 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68  tables] might ch
24480 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
24490 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20  e indirectly as 
244a0 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20 20  a side effect.  
244b0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
244c0 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  e, if an applica
244d0 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66  tion defines a f
244e0 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22  unction "eval()"
244f0 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20   that .** calls 
24500 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
24510 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f  , then the follo
24520 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  wing SQL stateme
24530 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e  nt would.** chan
24540 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
24550 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64  file through sid
24560 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a  e-effects:.**.**
24570 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
24580 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20  e>.**    SELECT 
24590 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f  eval('DELETE FRO
245a0 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a  M t1') FROM t2;.
245b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
245c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74  quote>.**.** But
245d0 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53 45   because the [SE
245e0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
245f0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
24600 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24610 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73  e.** directly, s
24620 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
24630 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69  only() would sti
24640 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29  ll return true.)
24650 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63  ^.**.** ^Transac
24660 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61  tion control sta
24670 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20  tements such as 
24680 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54  [BEGIN], [COMMIT
24690 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a  ], [ROLLBACK],.*
246a0 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61  * [SAVEPOINT], a
246b0 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75  nd [RELEASE] cau
246c0 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  se sqlite3_stmt_
246d0 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
246e0 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69  turn true,.** si
246f0 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  nce the statemen
24700 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f  ts themselves do
24710 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f   not actually mo
24720 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
24730 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20  e but.** rather 
24740 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65  they control the
24750 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20   timing of when 
24760 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73  other statements
24770 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20   modify the .** 
24780 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20  database.  ^The 
24790 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45  [ATTACH] and [DE
247a0 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73  TACH] statements
247b0 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73   also cause.** s
247c0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
247d0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
247e0 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69   true since, whi
247f0 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65  le those stateme
24800 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  nts.** change th
24810 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
24820 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  of a database co
24830 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64  nnection, they d
24840 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63  o not make .** c
24850 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f  hanges to the co
24860 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74  ntent of the dat
24870 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64  abase files on d
24880 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  isk..*/.SQLITE_A
24890 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
248a0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
248b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
248c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
248d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
248e0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
248f0 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
24900 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
24910 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
24920 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
24930 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24940 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
24950 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24960 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
24970 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
24980 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
24990 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
249a0 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
249b0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
249c0 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
249d0 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
249e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
249f0 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
24a00 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
24a10 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
24a20 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
24a30 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
24a40 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
24a50 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
24a60 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
24a70 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
24a80 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
24a90 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
24aa0 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
24ab0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
24ac0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
24ad0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
24ae0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
24af0 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
24b00 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
24b10 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
24b20 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
24b30 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
24b40 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
24b50 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
24b60 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
24b70 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
24b80 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
24b90 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
24ba0 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
24bb0 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
24bc0 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
24bd0 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
24be0 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
24bf0 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
24c00 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
24c10 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51  tion open..*/.SQ
24c20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
24c30 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
24c40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
24c50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24c60 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
24c70 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
24c80 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
24c90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24ca0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
24cb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
24cc0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
24cd0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
24ce0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
24cf0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
24d00 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
24d10 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
24d20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
24d30 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
24d40 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
24d50 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
24d60 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
24d70 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
24d80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
24d90 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
24da0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
24db0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
24dc0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
24dd0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
24de0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24df0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
24e00 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
24e10 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
24e20 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
24e30 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
24e40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24e50 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
24e60 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
24e70 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
24e80 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
24e90 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
24ea0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
24eb0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
24ec0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
24ed0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
24ee0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
24ef0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
24f00 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
24f10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24f20 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
24f30 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
24f40 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
24f50 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
24f60 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
24f70 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
24f80 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
24f90 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
24fa0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
24fb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
24fc0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
24fd0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
24fe0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
24ff0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25000 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
25010 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
25020 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
25030 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
25040 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
25050 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
25060 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
25070 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
25080 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
25090 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
250a0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
250b0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
250c0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
250d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
250e0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
250f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
25100 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
25110 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
25120 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
25130 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
25140 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
25150 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
25160 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
25170 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
25180 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
25190 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
251a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
251b0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
251c0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
251d0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
251e0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
251f0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
25200 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
25210 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
25220 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
25230 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
25240 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
25250 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
25260 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
25270 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
25280 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
25290 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
252a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
252b0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
252c0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
252d0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
252e0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
252f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
25300 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
25310 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
25320 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
25330 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
25340 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
25350 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
25360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
25370 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
25380 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
25390 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
253a0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
253b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
253c0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
253d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
253e0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
253f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25400 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
25410 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
25420 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
25430 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
25440 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
25450 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
25460 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
25470 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
25480 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
25490 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
254a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
254b0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
254c0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
254d0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
254e0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
254f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
25500 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
25510 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
25520 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
25530 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
25540 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
25550 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
25560 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
25570 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
25580 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
25590 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
255a0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
255b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
255c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
255d0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
255e0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
255f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
25600 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
25610 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
25620 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
25630 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
25640 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
25650 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
25660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
25670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
25680 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25690 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
256a0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
256b0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
256c0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
256d0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
256e0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
256f0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
25700 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
25710 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
25720 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
25730 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
25740 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
25750 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
25760 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
25770 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
25780 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
25790 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
257a0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
257b0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
257c0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
257d0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
257e0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
257f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
25800 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
25810 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
25820 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
25830 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
25840 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
25850 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
25860 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
25870 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
25880 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
25890 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
258a0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
258b0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
258c0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
258d0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
258e0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
258f0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
25900 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
25910 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
25920 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
25930 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
25940 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
25950 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
25960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
25970 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
25980 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
25990 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
259a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
259b0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
259c0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
259d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
259e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
259f0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
25a00 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
25a10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
25a20 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
25a30 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
25a40 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
25a50 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
25a60 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
25a70 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
25a80 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
25a90 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
25aa0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
25ab0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
25ac0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
25ad0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
25ae0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
25af0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
25b00 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
25b10 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
25b20 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
25b30 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
25b40 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
25b50 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25b60 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
25b70 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
25b80 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
25b90 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
25ba0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
25bb0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
25bc0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
25bd0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
25be0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
25bf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
25c00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25c10 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
25c20 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
25c30 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
25c40 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
25c50 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
25c60 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
25c70 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  er..**.** ^(In t
25c80 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
25c90 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
25ca0 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
25cb0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
25cc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25cd0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
25ce0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
25cf0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
25d00 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
25d10 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
25d20 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
25d30 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
25d40 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
25d50 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25d60 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ter is negative,
25d70 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
25d80 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
25d90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
25da0 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
25db0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
25dc0 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  tor..** If a non
25dd0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
25de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
25df0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
25e00 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
25e10 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
25e20 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
25e30 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
25e40 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
25e50 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
25e60 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
25e70 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
25e80 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
25e90 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
25ea0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
25eb0 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
25ec0 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
25ed0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
25ee0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
25ef0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
25f00 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
25f10 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
25f20 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
25f30 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
25f40 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
25f50 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
25f60 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
25f70 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
25f80 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
25f90 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
25fa0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
25fb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
25fc0 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
25fd0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
25fe0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
25ff0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
26000 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
26010 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
26020 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
26030 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
26040 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
26050 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
26060 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
26070 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
26080 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
26090 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
260a0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
260b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
260c0 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
260d0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
260e0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
260f0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
26100 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
26110 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
26120 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
26130 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
26140 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
26150 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
26160 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
26170 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
26180 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
26190 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
261a0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
261b0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
261c0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
261d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
261e0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
261f0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
26200 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
26210 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
26220 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
26230 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
26240 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
26250 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
26260 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
26270 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
26280 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
26290 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
262a0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
262b0 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
262c0 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
262d0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
262e0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
262f0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
26300 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
26310 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
26320 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
26330 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
26340 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
26350 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
26360 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
26370 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
26380 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
26390 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
263a0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
263b0 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
263c0 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
263d0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
263e0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
263f0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
26400 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
26410 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
26420 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
26430 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
26440 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
26450 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
26460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
26470 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
26480 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26490 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
264a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
264b0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
264c0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
264d0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
264e0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
264f0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
26500 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
26510 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
26520 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
26530 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
26540 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
26550 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
26560 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
26570 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
26580 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
26590 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
265a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
265b0 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
265c0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
265d0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
265e0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
265f0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
26600 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
26610 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
26620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
26630 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
26640 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
26650 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
26660 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
26670 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
26680 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
26690 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
266a0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
266b0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
266c0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
266d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
266e0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
266f0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
26700 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
26710 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26720 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
26730 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
26740 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
26750 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
26760 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
26770 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
26780 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
26790 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
267a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
267b0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
267c0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
267d0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
267e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
267f0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
26800 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
26810 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
26820 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26830 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
26840 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
26850 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26860 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
26870 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
26880 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
26890 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
268a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
268b0 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
268c0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
268d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
268e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
268f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
26900 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
26910 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
26920 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
26930 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
26940 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
26950 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
26960 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
26970 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
26980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
269a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
269b0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
269c0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
269d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
269e0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
269f0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
26a00 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
26a10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
26a20 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
26a30 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
26a40 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
26a50 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
26a60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
26a70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
26a80 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
26a90 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
26aa0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
26ab0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
26ac0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
26ad0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
26ae0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
26af0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
26b00 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
26b10 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
26b20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
26b30 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
26b40 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
26b50 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
26b60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
26b70 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
26b80 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
26b90 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
26ba0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
26bb0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
26bc0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
26bd0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
26be0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
26bf0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
26c00 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
26c10 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
26c20 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
26c30 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
26c40 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
26c50 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
26c60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
26c70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
26c80 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
26c90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
26ca0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26cb0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
26cc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
26cd0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
26ce0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
26cf0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
26d00 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
26d10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
26d20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26d30 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
26d40 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
26d50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
26d60 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
26d70 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
26d80 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
26d90 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
26da0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
26db0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
26dc0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
26dd0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
26de0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
26df0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
26e00 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
26e10 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
26e20 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
26e30 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
26e40 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
26e50 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
26e60 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
26e70 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
26e80 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
26e90 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
26ea0 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
26eb0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
26ec0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
26ed0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
26ee0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
26ef0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
26f00 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
26f10 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
26f20 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
26f30 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
26f40 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
26f50 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
26f60 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
26f70 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
26f80 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
26f90 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
26fa0 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
26fb0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
26fc0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
26fd0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
26fe0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
26ff0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
27000 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
27010 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
27020 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
27030 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
27040 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
27050 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
27060 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
27070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27080 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
27090 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
270a0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
270b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
270c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
270d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
270e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
270f0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
27100 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
27110 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
27120 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
27130 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27140 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
27150 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
27160 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
27170 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27180 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
27190 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
271a0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
271b0 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
271c0 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
271d0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
271e0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
271f0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
27200 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
27210 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
27220 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
27230 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
27240 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
27250 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
27260 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
27270 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
27280 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
27290 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
272a0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
272b0 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
272c0 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
272d0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
272e0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
272f0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
27300 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
27310 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
27320 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
27330 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
27340 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
27350 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
27360 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
27370 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
27380 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
27390 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
273a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
273b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
273c0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
273d0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
273e0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
273f0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
27400 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
27410 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
27420 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
27430 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
27440 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
27450 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
27460 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
27470 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
27480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
27490 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
274a0 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
274b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
274c0 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
274d0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
274e0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
274f0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
27500 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27510 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
27520 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
27530 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27540 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
27550 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
27560 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
27570 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
27580 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
27590 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
275a0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
275b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
275c0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
275d0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
275e0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
275f0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
27600 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
27610 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
27620 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
27630 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
27640 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
27650 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
27660 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27670 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
27680 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
27690 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
276a0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
276b0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
276c0 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
276d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
276e0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
276f0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
27700 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
27710 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
27720 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
27730 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
27740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27750 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
27760 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
27770 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
27780 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
27790 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
277a0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
277b0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
277c0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
277d0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
277e0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
277f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
27800 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
27810 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
27820 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
27830 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
27840 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
27850 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
27860 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
27870 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
27880 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
27890 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
278a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
278b0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
278c0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
278d0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
278e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
278f0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
27900 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27910 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
27920 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
27930 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
27940 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
27950 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
27960 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27970 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
27980 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
27990 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
279a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
279b0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
279c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
279d0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
279e0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
279f0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
27a00 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
27a10 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
27a20 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
27a30 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
27a40 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
27a50 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
27a60 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
27a70 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
27a80 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
27a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
27aa0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
27ab0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
27ac0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
27ad0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
27ae0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
27af0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
27b00 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
27b10 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
27b20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
27b30 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
27b40 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
27b50 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
27b60 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
27b70 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
27b80 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
27b90 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
27ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
27bb0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
27bc0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
27bd0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
27be0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
27bf0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
27c00 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
27c10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
27c20 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
27c30 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
27c40 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
27c50 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
27c60 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
27c70 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
27c80 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
27c90 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
27ca0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
27cb0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
27cc0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
27cd0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
27ce0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
27cf0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
27d00 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
27d10 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
27d20 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
27d30 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
27d40 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
27d50 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
27d60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
27d70 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
27d80 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
27d90 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27da0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
27db0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
27dc0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
27dd0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
27de0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
27df0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
27e00 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
27e10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27e20 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
27e30 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
27e40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27e50 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
27e60 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
27e70 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
27e80 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
27e90 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
27ea0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
27eb0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
27ec0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
27ed0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
27ee0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
27ef0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
27f00 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
27f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
27f20 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
27f30 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
27f40 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
27f50 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
27f60 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
27f70 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
27f80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
27f90 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
27fa0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
27fb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
27fc0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
27fd0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
27fe0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
27ff0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
28000 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
28010 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
28020 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
28030 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
28040 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
28050 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
28060 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
28070 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
28080 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
28090 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
280a0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
280b0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
280c0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
280d0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
280e0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
280f0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
28100 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
28110 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
28120 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
28130 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
28140 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
28150 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
28160 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
28170 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
28180 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
28190 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
281a0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
281b0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
281c0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
281d0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
281e0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
281f0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
28200 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
28210 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
28220 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
28230 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
28240 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
28250 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
28260 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
28270 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
28280 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
28290 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
282a0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
282b0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
282c0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
282d0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
282e0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
282f0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
28300 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
28310 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
28320 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
28330 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
28340 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
28350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
28360 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
28370 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
28380 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
28390 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
283a0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
283b0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
283c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
283d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
283e0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
283f0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
28400 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
28410 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
28420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
28430 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
28440 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
28450 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
28460 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28470 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
28480 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
28490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
284a0 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
284b0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
284c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
284d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
284e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
284f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
28500 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
28510 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28520 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
28530 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
28540 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
28550 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
28560 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
28570 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
28580 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
28590 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
285a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
285b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
285c0 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
285d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
285e0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
285f0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
28600 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
28610 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
28620 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28630 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
28640 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
28650 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
28660 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
28670 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
28680 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
28690 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
286a0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
286b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
286c0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
286d0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
286e0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
286f0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
28700 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
28710 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
28720 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
28730 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
28740 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
28750 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
28760 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
28770 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
28780 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
28790 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
287a0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
287b0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
287c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
287d0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
287e0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
287f0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
28800 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
28810 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
28820 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
28830 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
28840 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
28850 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
28860 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
28870 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
28880 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
28890 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
288a0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
288b0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
288c0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
288d0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
288e0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
288f0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
28900 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
28910 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28920 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
28930 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
28940 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
28950 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28960 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
28970 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
28980 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
28990 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
289a0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
289b0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
289c0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
289d0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
289e0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
289f0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
28a00 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
28a10 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
28a20 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
28a30 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
28a40 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
28a50 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
28a60 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
28a70 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
28a80 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
28a90 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
28aa0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
28ab0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
28ac0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
28ae0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
28af0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
28b00 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
28b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
28b20 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
28b30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
28b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
28b50 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
28b60 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
28b70 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
28b80 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
28b90 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
28ba0 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
28bb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
28bc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
28bd0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
28be0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
28bf0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
28c00 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
28c10 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
28c20 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
28c30 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
28c40 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
28c50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
28c60 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
28c70 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
28c80 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
28c90 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
28ca0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
28cb0 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
28cc0 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
28cd0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
28ce0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
28cf0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
28d00 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
28d10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
28d20 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
28d30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28d40 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
28d50 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
28d60 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
28d70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
28d80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28d90 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
28da0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
28db0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
28dc0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
28dd0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
28de0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
28df0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
28e00 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
28e10 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
28e20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
28e30 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
28e40 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
28e50 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
28e60 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
28e70 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
28e80 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
28e90 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
28ea0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
28eb0 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
28ec0 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
28ed0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
28ee0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
28ef0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
28f00 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
28f10 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
28f20 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
28f30 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
28f40 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
28f50 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
28f60 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
28f70 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
28f80 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
28f90 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
28fa0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
28fb0 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
28fc0 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
28fd0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
28fe0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
28ff0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
29000 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
29010 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
29020 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
29030 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
29040 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
29050 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
29060 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
29070 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
29080 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
29090 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
290a0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
290b0 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
290c0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
290d0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
290e0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
290f0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
29100 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
29110 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
29120 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
29130 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
29140 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
29150 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
29160 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
29170 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
29180 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
29190 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
291a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
291b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
291c0 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
291d0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
291e0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
291f0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
29200 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
29210 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
29220 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
29230 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
29240 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
29250 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
29260 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
29270 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
29280 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
29290 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
292a0 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
292b0 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
292c0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
292d0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
292e0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
292f0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
29300 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
29310 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
29320 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
29330 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
29340 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
29350 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
29360 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
29370 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
29380 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
29390 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
293a0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
293b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
293c0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
293d0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
293e0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
293f0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
29400 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
29410 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
29420 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
29430 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
29440 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
29450 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29460 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
29470 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29480 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
29490 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
294a0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
294b0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
294c0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
294d0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
294e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
294f0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
29500 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
29510 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
29520 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
29530 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
29540 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
29550 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29560 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
29570 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
29580 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
29590 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
295a0 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
295b0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
295c0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
295d0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
295e0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
295f0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
29600 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
29610 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
29620 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
29630 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
29640 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
29650 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
29660 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
29670 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
29680 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
29690 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
296a0 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
296b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
296c0 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
296d0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
296e0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
296f0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
29700 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
29710 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
29720 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
29730 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
29740 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
29750 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
29760 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29770 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
29780 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29790 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
297a0 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
297b0 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
297c0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
297d0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
297e0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
297f0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
29800 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
29810 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
29820 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
29830 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
29840 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
29850 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
29860 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
29870 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
29880 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
29890 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
298a0 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
298b0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
298c0 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
298d0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
298e0 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
298f0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
29900 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
29910 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
29920 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
29930 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
29940 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
29950 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
29960 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
29970 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
29980 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
29990 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
299a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
299b0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
299c0 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
299d0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
299e0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
299f0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
29a00 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
29a10 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
29a20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
29a30 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
29a40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
29a50 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
29a60 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
29a70 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
29a80 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
29a90 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
29aa0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
29ab0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
29ac0 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
29ad0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
29ae0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
29af0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
29b00 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
29b10 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
29b20 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
29b30 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
29b40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
29b50 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
29b60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
29b70 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
29b80 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
29b90 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
29ba0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
29bb0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
29bc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
29bd0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
29be0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
29bf0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
29c00 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
29c10 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
29c20 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
29c30 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
29c40 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
29c50 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
29c60 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  mmended..*/.SQLI
29c70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29c80 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
29c90 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
29ca0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
29cb0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
29cc0 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
29cd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29ce0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
29cf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
29d00 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
29d10 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
29d20 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
29d30 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
29d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29d50 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
29d60 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29d70 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
29d80 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
29d90 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
29da0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
29db0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
29dc0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
29dd0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
29de0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
29df0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
29e00 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
29e10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29e20 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
29e30 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
29e40 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
29e50 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
29e60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
29e70 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
29e80 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
29e90 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
29ea0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
29eb0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
29ec0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
29ed0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
29ee0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
29ef0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
29f00 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
29f10 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
29f20 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
29f30 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
29f40 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
29f50 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
29f60 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
29f70 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
29f80 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
29f90 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
29fa0 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
29fb0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
29fc0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
29fd0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
29fe0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
29ff0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2a000 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2a010 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a020 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2a030 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2a040 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a050 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
2a060 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
2a070 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
2a080 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
2a090 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
2a0a0 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
2a0b0 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
2a0c0 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
2a0d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2a0e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2a0f0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
2a100 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
2a110 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
2a120 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
2a130 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
2a140 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
2a150 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
2a160 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
2a170 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
2a180 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
2a190 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
2a1a0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
2a1b0 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
2a1c0 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
2a1d0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
2a1e0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
2a1f0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
2a200 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
2a210 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
2a220 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
2a230 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
2a240 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
2a250 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
2a260 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
2a270 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
2a280 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
2a290 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
2a2a0 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
2a2b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
2a2c0 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
2a2d0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
2a2e0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
2a2f0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
2a300 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
2a310 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
2a320 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
2a330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2a340 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
2a350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2a360 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
2a370 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
2a380 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
2a390 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
2a3a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2a3b0 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
2a3c0 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
2a3d0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
2a3e0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
2a3f0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
2a400 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
2a410 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
2a420 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
2a430 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
2a440 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
2a450 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a460 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
2a470 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
2a480 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2a490 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
2a4a0 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
2a4b0 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
2a4c0 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
2a4d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
2a4e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
2a4f0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
2a500 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
2a510 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2a520 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2a530 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
2a540 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
2a550 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
2a560 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
2a570 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
2a580 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
2a590 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
2a5a0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
2a5b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
2a5c0 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
2a5d0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
2a5e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2a5f0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
2a600 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2a610 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
2a620 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
2a630 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
2a640 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
2a650 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
2a660 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
2a670 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2a680 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
2a690 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
2a6a0 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
2a6b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2a6c0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2a6d0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2a6e0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2a6f0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
2a700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a710 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
2a720 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
2a730 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
2a740 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
2a750 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2a760 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2a770 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
2a780 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2a790 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a7a0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
2a7b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2a7c0 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
2a7d0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
2a7e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2a7f0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
2a800 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
2a810 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
2a820 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a830 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
2a840 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2a850 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
2a860 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
2a870 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
2a880 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
2a890 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
2a8a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
2a8b0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2a8c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2a8d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2a8e0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
2a8f0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
2a900 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
2a910 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
2a920 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
2a930 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
2a940 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
2a950 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
2a960 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
2a970 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
2a980 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
2a990 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
2a9a0 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
2a9b0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
2a9c0 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
2a9d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2a9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
2a9f0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
2aa00 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
2aa10 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
2aa20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
2aa30 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
2aa40 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
2aa50 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
2aa60 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
2aa70 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2aa80 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
2aa90 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
2aaa0 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
2aab0 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
2aac0 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
2aad0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
2aae0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
2aaf0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
2ab00 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
2ab10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2ab20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
2ab30 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
2ab40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ab50 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
2ab60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
2ab70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ab80 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
2ab90 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2aba0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
2abb0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
2abc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2abd0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
2abe0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
2abf0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
2ac00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ac10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2ac20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ac30 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2ac40 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2ac50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
2ac60 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2ac70 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2ac80 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2ac90 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
2aca0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2acb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2acc0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2acd0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2ace0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2acf0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2ad00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
2ad10 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2ad20 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ad30 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2ad40 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
2ad50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2ad60 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
2ad70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ad80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ad90 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2ada0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2adb0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2adc0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
2add0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2ade0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2adf0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
2ae00 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
2ae10 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
2ae20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ae30 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
2ae40 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
2ae50 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
2ae60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ae70 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
2ae80 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
2ae90 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
2aea0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
2aeb0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2aec0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
2aed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2aee0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
2aef0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2af00 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
2af10 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2af20 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
2af30 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2af40 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
2af50 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2af60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
2af70 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2af80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2af90 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
2afa0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
2afb0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
2afc0 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
2afd0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
2afe0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
2aff0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2b000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2b010 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
2b020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2b030 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
2b040 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
2b050 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
2b060 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2b070 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
2b080 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
2b090 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2b0a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
2b0b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2b0c0 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
2b0d0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
2b0e0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
2b0f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
2b100 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
2b110 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2b120 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
2b130 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
2b140 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
2b150 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
2b160 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
2b170 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
2b180 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2b190 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
2b1a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b1b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
2b1c0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2b1d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b1e0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
2b1f0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
2b200 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
2b210 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b220 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
2b230 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
2b240 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b250 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
2b260 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2b270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2b280 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
2b290 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
2b2a0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
2b2b0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
2b2c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
2b2d0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
2b2e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
2b2f0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
2b300 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
2b310 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2b320 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2b330 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
2b340 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
2b350 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
2b360 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
2b370 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
2b380 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
2b390 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
2b3a0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
2b3b0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
2b3c0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
2b3d0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
2b3e0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
2b3f0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
2b400 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
2b410 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
2b420 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
2b430 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
2b440 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
2b450 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
2b460 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
2b470 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
2b480 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
2b490 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
2b4a0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
2b4b0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
2b4c0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
2b4d0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
2b4e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2b4f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2b500 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2b510 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
2b520 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
2b530 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
2b540 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
2b550 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b560 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2b570 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2b580 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2b590 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2b5a0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b5b0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
2b5c0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
2b5d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2b5e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2b5f0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
2b600 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
2b610 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2b620 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
2b630 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
2b640 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
2b650 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
2b660 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2b670 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
2b680 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
2b690 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2b6a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2b6b0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2b6c0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
2b6d0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
2b6e0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2b6f0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2b700 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2b710 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2b720 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2b730 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2b740 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2b750 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
2b760 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2b770 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
2b780 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
2b790 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2b7a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
2b7b0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
2b7c0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
2b7d0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2b7e0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2b7f0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2b800 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2b810 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2b820 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
2b830 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
2b840 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
2b850 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
2b860 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2b870 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
2b880 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
2b890 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2b8a0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2b8b0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
2b8c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
2b8d0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
2b8e0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2b8f0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
2b900 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
2b910 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
2b920 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
2b930 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
2b940 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
2b950 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
2b960 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
2b970 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
2b980 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
2b990 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
2b9a0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
2b9b0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
2b9c0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
2b9d0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
2b9e0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
2b9f0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
2ba00 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
2ba10 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
2ba20 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
2ba30 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
2ba40 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
2ba50 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
2ba60 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
2ba70 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
2ba80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2ba90 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
2baa0 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
2bab0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
2bac0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
2bad0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
2bae0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
2baf0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
2bb00 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
2bb10 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
2bb20 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2bb30 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
2bb40 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2bb50 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2bb60 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
2bb70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2bb80 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
2bb90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2bba0 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
2bbb0 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
2bbc0 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
2bbd0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
2bbe0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
2bbf0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2bc00 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2bc10 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
2bc20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2bc30 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
2bc40 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
2bc50 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
2bc60 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
2bc70 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
2bc80 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
2bc90 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
2bca0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
2bcb0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
2bcc0 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
2bcd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bce0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
2bcf0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2bd00 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
2bd10 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
2bd20 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
2bd30 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
2bd40 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
2bd50 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
2bd60 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
2bd70 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
2bd80 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
2bd90 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
2bda0 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
2bdb0 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
2bdc0 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
2bdd0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
2bde0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
2bdf0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2be00 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
2be10 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
2be20 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
2be30 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
2be40 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
2be50 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
2be60 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
2be70 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
2be80 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
2be90 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
2bea0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
2beb0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
2bec0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
2bed0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
2bee0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
2bef0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
2bf00 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
2bf10 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
2bf20 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
2bf30 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
2bf40 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
2bf50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bf60 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
2bf70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bf80 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
2bf90 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2bfa0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
2bfb0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2bfc0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2bfd0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2bfe0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2bff0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
2c000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c010 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
2c020 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
2c030 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
2c040 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
2c050 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c060 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
2c070 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
2c080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2c090 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
2c0a0 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
2c0b0 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
2c0c0 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
2c0d0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
2c0e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c0f0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2c100 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c110 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
2c120 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
2c130 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
2c140 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
2c150 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
2c160 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c170 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
2c180 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
2c190 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c1a0 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
2c1b0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
2c1c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2c1d0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
2c1e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
2c1f0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
2c200 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
2c210 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
2c220 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
2c230 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
2c240 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
2c250 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
2c260 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c270 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2c280 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2c290 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c2a0 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
2c2b0 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
2c2c0 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
2c2d0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
2c2e0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
2c2f0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
2c300 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
2c310 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2c320 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
2c330 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
2c340 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c350 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
2c360 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
2c370 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
2c380 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
2c390 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
2c3a0 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
2c3b0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
2c3c0 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
2c3d0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
2c3e0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
2c3f0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
2c400 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
2c410 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
2c420 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
2c430 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
2c440 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
2c450 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
2c460 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
2c470 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
2c480 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
2c490 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
2c4a0 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
2c4b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c4c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2c4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c4e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c4f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2c510 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c520 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c530 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c540 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
2c550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c560 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
2c570 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
2c580 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2c590 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c5a0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
2c5b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c5c0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
2c5d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2c5e0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2c5f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
2c600 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2c610 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2c620 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2c630 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
2c640 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2c650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c660 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2c670 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2c680 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2c690 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2c6a0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2c6b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2c6c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2c6d0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c6e0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2c6f0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c700 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2c710 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
2c720 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
2c730 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2c740 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
2c750 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
2c760 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
2c770 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2c780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c790 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
2c7a0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
2c7b0 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
2c7c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c7d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
2c7e0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
2c7f0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
2c800 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
2c810 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
2c820 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
2c830 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
2c840 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
2c850 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2c860 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
2c870 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
2c880 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2c890 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
2c8a0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
2c8b0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
2c8c0 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
2c8d0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
2c8e0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
2c8f0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2c900 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
2c910 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c920 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
2c930 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
2c940 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
2c950 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
2c960 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
2c970 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c980 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
2c990 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
2c9a0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
2c9b0 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
2c9c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
2c9d0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
2c9e0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
2c9f0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
2ca00 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
2ca10 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
2ca20 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
2ca30 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
2ca40 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
2ca50 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
2ca60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
2ca70 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
2ca80 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
2ca90 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
2caa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
2cab0 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
2cac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cad0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
2cae0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
2caf0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
2cb00 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
2cb10 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2cb20 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
2cb30 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
2cb40 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
2cb50 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
2cb60 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
2cb70 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
2cb80 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
2cb90 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2cba0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
2cbb0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
2cbc0 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
2cbd0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
2cbe0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
2cbf0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
2cc00 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
2cc10 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  PI int sqlite3_f
2cc20 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
2cc30 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2cc40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2cc50 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
2cc60 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2cc70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2cc80 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
2cc90 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
2cca0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
2ccb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2ccc0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
2ccd0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
2cce0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
2ccf0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
2cd00 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
2cd10 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
2cd20 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
2cd30 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
2cd40 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2cd50 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
2cd60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
2cd70 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
2cd80 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
2cd90 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2cda0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
2cdb0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
2cdc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
2cdd0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
2cde0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
2cdf0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ce00 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
2ce10 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
2ce20 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
2ce30 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
2ce40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2ce50 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2ce60 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
2ce70 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ce80 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
2ce90 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
2cea0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
2ceb0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
2cec0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
2ced0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
2cee0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
2cef0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
2cf00 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2cf10 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
2cf20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
2cf30 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2cf40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2cf50 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
2cf60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cf70 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
2cf80 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
2cf90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cfa0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
2cfb0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2cfc0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
2cfd0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2cfe0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2cff0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2d000 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
2d010 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
2d020 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
2d030 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
2d040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
2d050 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d060 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
2d070 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2d080 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2d090 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
2d0a0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
2d0b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
2d0c0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
2d0d0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
2d0e0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
2d0f0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2d100 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d110 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
2d120 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
2d130 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2d140 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
2d150 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
2d160 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
2d170 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
2d180 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
2d190 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
2d1a0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
2d1b0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
2d1c0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
2d1d0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
2d1e0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
2d1f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
2d200 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
2d210 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
2d220 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
2d230 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
2d240 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
2d250 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
2d260 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2d270 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
2d280 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
2d290 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
2d2a0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
2d2b0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
2d2c0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
2d2d0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
2d2e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2d2f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2d300 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2d310 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
2d320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2d330 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
2d340 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
2d350 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
2d360 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
2d370 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
2d380 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
2d390 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
2d3a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2d3b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d3c0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
2d3d0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
2d3e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d3f0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
2d400 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
2d410 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
2d420 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
2d430 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
2d440 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
2d450 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
2d460 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
2d470 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
2d480 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
2d490 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
2d4a0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
2d4b0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
2d4c0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
2d4d0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
2d4e0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
2d4f0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
2d500 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
2d510 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
2d520 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
2d530 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
2d540 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
2d550 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
2d560 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
2d570 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
2d580 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
2d590 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
2d5a0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
2d5b0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2d5c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
2d5d0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2d5e0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2d5f0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
2d600 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
2d610 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
2d620 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
2d630 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
2d640 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
2d650 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
2d660 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
2d670 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
2d680 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2d690 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2d6a0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
2d6b0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
2d6c0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
2d6d0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
2d6e0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
2d6f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
2d700 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2d710 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
2d720 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
2d730 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
2d740 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
2d750 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
2d760 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
2d770 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
2d780 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
2d790 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
2d7a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2d7b0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
2d7c0 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
2d7d0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
2d7e0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
2d7f0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
2d800 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
2d810 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
2d820 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
2d830 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
2d840 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
2d850 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
2d860 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
2d870 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
2d880 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
2d890 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
2d8a0 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
2d8b0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
2d8c0 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
2d8d0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
2d8e0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
2d8f0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
2d900 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2d910 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
2d920 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
2d930 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
2d940 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
2d950 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
2d960 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
2d970 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
2d980 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
2d990 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
2d9a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2d9b0 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
2d9c0 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
2d9d0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
2d9e0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
2d9f0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
2da00 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
2da10 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
2da20 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
2da30 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
2da40 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
2da50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
2da60 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
2da70 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
2da80 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
2da90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
2daa0 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
2dab0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
2dac0 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
2dad0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
2dae0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
2daf0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
2db00 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
2db10 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
2db20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2db30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2db40 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
2db50 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
2db60 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
2db70 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
2db80 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
2db90 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
2dba0 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
2dbb0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2dbc0 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
2dbd0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
2dbe0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
2dbf0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
2dc00 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
2dc10 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
2dc20 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
2dc30 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
2dc40 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
2dc50 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
2dc60 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
2dc70 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
2dc80 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2dc90 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
2dca0 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
2dcb0 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
2dcc0 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
2dcd0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
2dce0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2dcf0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2dd00 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
2dd10 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
2dd20 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
2dd30 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2dd40 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2dd50 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
2dd60 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
2dd70 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
2dd80 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
2dd90 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
2dda0 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
2ddb0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2ddc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
2ddd0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
2dde0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
2ddf0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
2de00 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2de10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2de20 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
2de30 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
2de40 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
2de50 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
2de60 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
2de70 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
2de80 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
2de90 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
2dea0 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
2deb0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
2dec0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
2ded0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
2dee0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2def0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2df00 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
2df10 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
2df20 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
2df30 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
2df40 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
2df50 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
2df60 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
2df70 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
2df80 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
2df90 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
2dfa0 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
2dfb0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2dfc0 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
2dfd0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
2dfe0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2dff0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
2e000 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
2e010 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
2e020 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2e030 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
2e040 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2e050 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
2e060 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
2e070 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2e080 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
2e090 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
2e0a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
2e0b0 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
2e0c0 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
2e0d0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
2e0e0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
2e0f0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
2e100 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
2e110 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
2e120 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
2e130 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2e140 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
2e150 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
2e160 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
2e170 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
2e180 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
2e190 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
2e1a0 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
2e1b0 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
2e1c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
2e1d0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
2e1e0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
2e1f0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
2e200 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
2e210 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
2e220 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
2e230 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
2e240 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e250 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
2e260 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
2e270 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e280 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
2e290 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
2e2a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
2e2b0 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
2e2c0 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
2e2d0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
2e2e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e2f0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
2e300 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
2e310 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2e320 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
2e330 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2e340 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
2e350 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2e360 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2e370 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2e380 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2e390 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2e3a0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2e3b0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2e3c0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2e3d0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2e3e0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e3f0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e400 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2e410 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2e420 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2e430 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2e440 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2e450 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
2e460 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2e470 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2e480 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2e490 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
2e4a0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2e4b0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2e4c0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2e4d0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2e4e0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2e4f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2e500 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2e510 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2e520 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e530 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2e540 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2e550 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2e560 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
2e570 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e580 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2e590 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
2e5a0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2e5b0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
2e5c0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2e5d0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e5e0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2e5f0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2e600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2e610 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2e620 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2e630 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2e640 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2e650 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2e660 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2e670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
2e680 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
2e690 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
2e6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
2e6b0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
2e6c0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2e6d0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
2e6e0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
2e6f0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
2e700 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
2e710 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
2e720 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
2e730 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
2e740 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2e750 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2e760 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
2e770 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2e780 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
2e790 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2e7a0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
2e7b0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
2e7c0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
2e7d0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
2e7e0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
2e7f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2e800 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
2e810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e820 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
2e830 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2e840 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
2e850 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
2e860 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
2e870 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
2e880 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
2e890 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2e8a0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
2e8b0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
2e8c0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
2e8d0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2e8e0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
2e8f0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
2e900 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
2e910 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
2e920 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
2e930 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
2e940 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
2e950 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
2e960 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
2e970 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
2e980 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
2e990 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
2e9a0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
2e9b0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
2e9c0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
2e9d0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
2e9e0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
2e9f0 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20  ATED.SQLITE_API 
2ea00 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ea10 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2ea20 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2ea30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2ea40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2ea50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
2ea60 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
2ea70 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
2ea80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
2ea90 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2eaa0 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
2eab0 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
2eac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
2ead0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
2eae0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2eaf0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2eb00 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
2eb10 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
2eb20 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2eb30 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
2eb40 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
2eb50 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
2eb60 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2eb70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2eb80 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
2eb90 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
2eba0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
2ebb0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
2ebc0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
2ebd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ebe0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
2ebf0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
2ec00 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
2ec10 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
2ec20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
2ec30 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
2ec40 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
2ec50 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
2ec60 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2ec70 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
2ec80 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
2ec90 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
2eca0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
2ecb0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
2ecc0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
2ecd0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
2ece0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
2ecf0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
2ed00 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2ed10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2ed20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
2ed30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
2ed40 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
2ed50 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
2ed60 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
2ed70 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2ed80 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
2ed90 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2eda0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
2edb0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
2edc0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2edd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ede0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2edf0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2ee00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ee10 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2ee20 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2ee30 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2ee40 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2ee50 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2ee60 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2ee70 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2ee80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2ee90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2eea0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2eeb0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2eec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2eed0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2eee0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2eef0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2ef00 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2ef10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2ef20 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2ef30 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2ef40 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
2ef50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2ef60 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2ef70 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
2ef80 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2ef90 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
2efa0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
2efb0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
2efc0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
2efd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2efe0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
2eff0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
2f000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
2f010 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
2f020 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
2f030 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
2f040 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2f050 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
2f060 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
2f070 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
2f080 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
2f090 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2f0a0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
2f0b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2f0c0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2f0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2f0e0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2f0f0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2f100 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2f110 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2f120 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2f130 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2f140 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
2f150 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2f160 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
2f170 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
2f180 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
2f190 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
2f1a0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
2f1b0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
2f1c0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
2f1d0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2f1e0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
2f1f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
2f200 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
2f210 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
2f220 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
2f230 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
2f240 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
2f250 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
2f260 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
2f270 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
2f280 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
2f290 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2f2a0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
2f2b0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
2f2c0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
2f2d0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
2f2e0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2f2f0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2f300 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
2f310 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
2f320 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2f330 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2f340 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2f350 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2f360 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2f370 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2f380 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f390 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2f3a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f3b0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2f3c0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2f3d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2f3e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2f3f0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2f400 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2f410 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2f420 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2f430 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2f440 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2f450 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2f460 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2f470 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2f480 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2f490 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2f4a0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2f4b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2f4c0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
2f4d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2f4e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2f4f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
2f500 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2f510 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2f520 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
2f530 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f540 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2f560 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
2f570 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2f580 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
2f590 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2f5a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f5b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f5c0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
2f5d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f5e0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
2f5f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2f600 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
2f610 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f620 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
2f630 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
2f640 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2f650 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2f660 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f670 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f680 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2f690 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2f6a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f6b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2f6c0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
2f6d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2f6e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2f6f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2f700 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
2f710 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2f720 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f730 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
2f740 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2f750 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f760 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
2f770 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
2f780 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
2f790 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2f7a0 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
2f7b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
2f7c0 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
2f7d0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
2f7e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
2f7f0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
2f800 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
2f810 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
2f820 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
2f830 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2f840 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
2f850 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2f860 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
2f870 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
2f880 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
2f890 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2f8a0 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
2f8b0 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
2f8c0 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
2f8d0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
2f8e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2f8f0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
2f900 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
2f910 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2f920 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
2f930 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2f940 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
2f950 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
2f960 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
2f970 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
2f980 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
2f990 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
2f9a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2f9b0 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
2f9c0 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
2f9d0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
2f9e0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
2f9f0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
2fa00 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
2fa10 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
2fa20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2fa30 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
2fa40 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
2fa50 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2fa60 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
2fa70 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
2fa80 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
2fa90 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2faa0 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
2fab0 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
2fac0 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
2fad0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
2fae0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
2faf0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2fb00 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
2fb10 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
2fb20 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
2fb30 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
2fb40 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
2fb50 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2fb60 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
2fb70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
2fb80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
2fb90 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
2fba0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
2fbb0 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
2fbc0 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
2fbd0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
2fbe0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
2fbf0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
2fc00 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
2fc10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
2fc20 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
2fc30 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
2fc40 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
2fc50 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
2fc60 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
2fc70 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
2fc80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
2fc90 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
2fca0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
2fcb0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
2fcc0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
2fcd0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
2fce0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
2fcf0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
2fd00 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
2fd10 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
2fd20 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
2fd30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
2fd40 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
2fd50 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2fd60 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
2fd70 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
2fd80 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
2fd90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2fda0 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
2fdb0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
2fdc0 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
2fdd0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
2fde0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
2fdf0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
2fe00 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
2fe10 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2fe20 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
2fe30 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
2fe40 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
2fe50 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2fe60 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2fe70 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2fe80 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2fe90 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
2fea0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2feb0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
2fec0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
2fed0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
2fee0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
2fef0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2ff00 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
2ff10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
2ff20 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
2ff30 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
2ff40 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2ff50 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
2ff60 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
2ff70 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
2ff80 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
2ff90 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
2ffa0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
2ffb0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
2ffc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2ffd0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
2ffe0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2fff0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
30000 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
30010 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
30020 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
30030 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
30040 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
30050 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
30060 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
30070 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
30080 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
30090 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
300a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
300b0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
300c0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
300d0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
300e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
300f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30100 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
30110 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
30120 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
30130 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
30140 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
30150 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
30160 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
30170 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
30180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30190 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
301a0 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
301b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
301c0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
301d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
301e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
301f0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
30200 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
30210 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
30220 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
30230 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
30240 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
30250 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
30260 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
30270 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
30280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30290 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
302a0 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
302b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
302c0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
302d0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
302e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
302f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
30300 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
30310 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
30320 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
30330 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
30340 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
30350 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
30360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
30370 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
30380 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
30390 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
303a0 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
303b0 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
303c0 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
303d0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
303e0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
303f0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
30400 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
30410 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
30420 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
30430 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
30440 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
30450 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
30460 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
30470 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
30480 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
30490 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
304a0 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
304b0 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
304c0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
304d0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
304e0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
304f0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
30500 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
30510 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
30520 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
30530 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
30540 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
30550 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
30560 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
30570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
30580 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
30590 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
305a0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
305b0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
305c0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
305d0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
305e0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
305f0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
30600 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
30610 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
30620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
30630 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
30640 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
30650 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
30660 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
30670 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
30680 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
30690 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
306a0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
306b0 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
306c0 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
306d0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
306e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
306f0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
30700 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
30710 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
30720 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
30730 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
30740 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
30750 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
30760 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
30770 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
30780 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
30790 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
307a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
307b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
307c0 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
307d0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
307e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
307f0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
30800 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
30810 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
30820 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
30830 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
30840 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
30850 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
30860 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
30870 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
30880 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
30890 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
308a0 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
308b0 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
308c0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
308d0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
308e0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
308f0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
30900 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
30910 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
30920 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
30930 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
30940 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
30950 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
30960 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
30970 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
30980 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
30990 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
309a0 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
309b0 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
309c0 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
309d0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
309e0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
309f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
30a00 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
30a10 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
30a20 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
30a30 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
30a40 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
30a50 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
30a60 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
30a70 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
30a80 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
30a90 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
30aa0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
30ab0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
30ac0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
30ad0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
30ae0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
30af0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
30b00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
30b10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
30b20 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
30b30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
30b40 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
30b50 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
30b60 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
30b70 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
30b80 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
30b90 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
30ba0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
30bb0 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
30bc0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
30bd0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
30be0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
30bf0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
30c00 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
30c10 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
30c20 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
30c30 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
30c40 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30c50 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
30c60 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
30c70 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
30c80 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
30c90 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
30ca0 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
30cb0 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
30cc0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
30cd0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
30ce0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
30cf0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
30d00 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
30d10 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
30d20 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
30d30 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
30d40 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
30d50 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
30d60 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
30d70 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
30d80 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
30d90 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
30da0 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
30db0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
30dc0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
30dd0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
30de0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
30df0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
30e00 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
30e10 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
30e20 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
30e30 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
30e40 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
30e50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
30e60 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
30e70 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
30e80 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
30e90 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
30ea0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
30eb0 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
30ec0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30ed0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
30ee0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
30ef0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
30f00 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
30f10 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
30f20 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
30f30 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
30f40 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
30f50 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
30f60 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
30f70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30f80 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
30f90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30fa0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
30fb0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
30fc0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
30fd0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30fe0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
30ff0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
31000 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
31010 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
31020 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
31030 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
31040 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
31050 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
31060 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
31070 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
31080 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
31090 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
310a0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
310b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
310c0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
310d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
310e0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
310f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
31100 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
31110 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
31120 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
31130 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
31140 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
31150 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
31160 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
31170 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
31180 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
31190 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
311a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
311b0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
311c0 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
311d0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
311e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
311f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
31200 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
31210 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
31220 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
31230 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
31240 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
31250 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31270 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
31280 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
31290 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
312a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
312b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
312c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
312d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
312e0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
312f0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
31300 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
31310 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31320 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
31330 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31340 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
31350 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
31360 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
31370 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
31380 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
31390 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
313a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
313b0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
313c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
313d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
313e0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
313f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
31400 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
31410 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
31420 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
31430 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
31440 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
31450 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
31460 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
31470 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
31480 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
31490 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
314a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
314b0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
314c0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
314d0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
314e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
314f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
31500 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
31510 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
31520 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
31530 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
31540 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
31550 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
31560 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
31570 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
31580 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
31590 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
315a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
315b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
315c0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
315d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
315e0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
315f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
31600 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
31610 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
31620 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
31630 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
31640 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
31650 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
31660 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31670 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
31680 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
31690 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
316a0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
316b0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
316c0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
316d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
316e0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
316f0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
31700 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
31710 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
31720 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
31730 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
31740 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
31750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
31760 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
31770 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
31780 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
31790 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
317a0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
317b0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
317c0 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
317d0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
317e0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
317f0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
31800 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
31810 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31820 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
31830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31840 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
31850 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
31860 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
31870 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31880 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
31890 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
318a0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
318b0 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
318c0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
318d0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
318e0 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
318f0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
31900 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31910 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
31920 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
31930 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
31940 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
31950 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
31960 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
31970 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
31980 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
31990 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
319a0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
319b0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
319c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
319d0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
319e0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
319f0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
31a00 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
31a10 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
31a20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31a30 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
31a40 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
31a50 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
31a60 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31a70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31a80 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
31a90 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
31aa0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
31ab0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
31ac0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
31ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
31ae0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
31af0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
31b00 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
31b10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
31b20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
31b30 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
31b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31b50 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
31b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31b70 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
31b80 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31b90 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
31ba0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
31bb0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
31bc0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
31bd0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
31be0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31bf0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
31c00 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
31c10 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
31c20 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
31c30 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
31c40 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
31c50 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
31c60 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
31c70 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
31c80 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
31c90 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
31ca0 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
31cb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
31cc0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
31cd0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
31ce0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
31cf0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
31d00 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
31d10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
31d20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31d30 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
31d40 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
31d50 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
31d60 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
31d70 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
31d80 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
31d90 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
31da0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
31db0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
31dc0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
31dd0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
31de0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
31df0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
31e00 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
31e10 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
31e20 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
31e30 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
31e40 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
31e50 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
31e60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31e70 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
31e80 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68  n result.  If th
31e90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
31ea0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
31eb0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74   then it.** must
31ec0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
31ed0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72  set into the str
31ee0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55  ing where the NU
31ef0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
31f00 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20  ld.** appear if 
31f10 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
31f20 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e   NUL terminated.
31f30 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
31f40 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a  racters occur.**
31f50 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61   in the string a
31f60 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20  t a byte offset 
31f70 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61  that is less tha
31f80 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  n the value of t
31f90 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65  he 3rd.** parame
31fa0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ter, then the re
31fb0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77  sulting string w
31fc0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  ill contain embe
31fd0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68  dded NULs and th
31fe0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65  e.** result of e
31ff0 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61  xpressions opera
32000 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20  ting on strings 
32010 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
32020 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
32030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
32040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32060 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
32070 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
32080 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20  esult_blob is a 
32090 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
320a0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61  , then SQLite ca
320b0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63  lls that.** func
320c0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74  tion as the dest
320d0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65  ructor on the te
320e0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
320f0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a  t when it has.**
32100 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
32110 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
32120 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
32130 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
32140 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
32150 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20  * interfaces or 
32160 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  to.** sqlite3_re
32170 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
32180 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
32190 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  t SQLITE_STATIC,
321a0 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20   then SQLite.** 
321b0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
321c0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
321d0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74  sult is in const
321e0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ant space and do
321f0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74  es not.** copy t
32200 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
32210 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20  e parameter nor 
32220 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f  call a destructo
32230 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74  r on the content
32240 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20  .** when it has 
32250 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
32260 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
32270 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
32280 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
32290 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
322a0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
322b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
322c0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
322d0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
322e0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a  LITE_TRANSIENT.*
322f0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61  * then SQLite ma
32300 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
32310 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70  e result into sp
32320 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ace obtained fro
32330 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  m.** from [sqlit
32340 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66  e3_malloc()] bef
32350 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a  ore it returns..
32360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32370 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
32380 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
32390 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
323a0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
323b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
323c0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20  on to be a copy 
323d0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63  the.** [unprotec
323e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
323f0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  e] object specif
32400 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70  ied by the 2nd p
32410 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a  arameter.  ^The.
32420 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
32430 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
32440 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
32450 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
32460 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
32470 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
32480 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
32490 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
324a0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
324b0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
324c0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
324d0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
324e0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
324f0 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74  arm..** ^A [prot
32500 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32510 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20  lue] object may 
32520 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77  always be used w
32530 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  here an.** [unpr
32540 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
32550 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73  value] object is
32560 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69   required, so ei
32570 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20  ther.** kind of 
32580 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
32590 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73  object can be us
325a0 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74  ed with this int
325b0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66  erface..**.** If
325c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
325d0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
325e0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65  within the diffe
325f0 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74  rent thread.** t
32600 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74  han the one cont
32610 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69  aining the appli
32620 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32630 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63  unction that rec
32640 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71  eived.** the [sq
32650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70  lite3_context] p
32660 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75  ointer, the resu
32670 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
32680 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
32690 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
326a0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
326b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
326c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
326d0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
326e0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
326f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
32700 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
32710 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
32720 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
32730 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32740 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
32750 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
32760 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  r*, int);.SQLITE
32770 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32780 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32790 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
327a0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
327b0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
327c0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
327d0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
327e0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
327f0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
32800 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32810 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
32820 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32830 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
32840 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
32850 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c  t_error_code(sql
32860 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
32870 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32880 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32890 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
328a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
328b0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
328c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
328d0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nt64(sqlite3_con
328e0 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69  text*, sqlite3_i
328f0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
32900 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
32910 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
32920 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
32930 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32940 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32950 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
32960 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
32970 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
32980 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
32990 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
329a0 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c  esult_text16(sql
329b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
329c0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
329d0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
329e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
329f0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32a00 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
32a10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32a20 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
32a30 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
32a40 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
32a50 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
32a60 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16be(sqlite3_co
32a70 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32a80 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
32a90 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
32aa0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
32ab0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
32ac0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
32ad0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
32ae0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
32af0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32b00 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
32b10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
32b20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
32b30 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20  REF: Define New 
32b40 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e  Collating Sequen
32b50 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ces.**.** ^These
32b60 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
32b70 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
32b80 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
32b90 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
32ba0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
32bb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
32bc0 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
32bd0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
32be0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
32bf0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
32c00 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
32c10 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
32c20 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32c30 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
32c40 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32c50 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
32c60 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
32c70 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
32c80 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
32c90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
32ca0 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
32cb0 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
32cc0 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
32cd0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
32ce0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
32cf0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
32d00 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
32d10 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
32d20 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
32d30 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
32d40 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
32d50 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
32d60 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
32d70 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
32d80 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
32d90 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
32da0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
32db0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
32dc0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
32dd0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
32de0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
32df0 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
32e00 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
32e10 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
32e20 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
32e30 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
32e40 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
32e50 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
32e60 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
32e70 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
32e80 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
32e90 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
32ea0 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
32eb0 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
32ec0 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
32ed0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
32ee0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
32ef0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
32f00 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
32f10 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
32f20 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
32f30 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
32f40 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
32f50 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
32f60 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
32f70 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32f80 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
32f90 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
32fa0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
32fb0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
32fc0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32fd0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
32fe0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
32ff0 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
33000 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
33010 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
33020 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
33030 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
33040 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
33050 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
33060 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
33070 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
33080 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
33090 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
330a0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
330b0 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
330c0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
330d0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
330e0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
330f0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
33100 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
33110 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
33120 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
33130 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
33140 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
33150 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
33160 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
33170 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
33180 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
33190 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
331a0 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
331b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
331c0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
331d0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
331e0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
331f0 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
33200 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33210 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
33220 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
33230 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
33240 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
33250 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
33260 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
33270 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
33280 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
33290 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
332a0 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
332b0 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
332c0 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
332d0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
332e0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
332f0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
33300 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
33310 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
33320 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
33330 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
33340 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
33350 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20   given the same 
33360 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20  inputs.  If two 
33370 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e  or more collatin
33380 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
33390 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f  registered.** to
333a0 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74   the same collat
333b0 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20  ion name (using 
333c0 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52  different eTextR
333d0 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20  ep values) then 
333e0 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65  all.** must give
333f0 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61   an equivalent a
33400 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b  nswer when invok
33410 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65  ed with equivale
33420 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  nt strings..** T
33430 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
33440 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20  ction must obey 
33450 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72  the following pr
33460 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c  operties for all
33470 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42  .** strings A, B
33480 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c  , and C:.**.** <
33490 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ol>.** <li> If A
334a0 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a  ==B then B==A..*
334b0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61  * <li> If A==B a
334c0 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d  nd B==C then A==
334d0 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  C..** <li> If A&
334e0 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41  lt;B THEN B&gt;A
334f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
33500 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74  t;B and B&lt;C t
33510 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c  hen A&lt;C..** <
33520 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  /ol>.**.** If a 
33530 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
33540 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20  on fails any of 
33550 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72  the above constr
33560 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a  aints and that.*
33570 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  * collating func
33580 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65  tion is  registe
33590 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68  red and used, th
335a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
335b0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20  of SQLite.** is 
335c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
335d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72   ^The sqlite3_cr
335e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
335f0 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  2() works like s
33600 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
33610 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74  llation().** wit
33620 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74  h the addition t
33630 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79  hat the xDestroy
33640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
33650 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65  oked on pArg whe
33660 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69  n.** the collati
33670 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64  ng function is d
33680 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c  eleted..** ^Coll
33690 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
336a0 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e  are deleted when
336b0 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
336c0 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a  dden by later.**
336d0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f   calls to the co
336e0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
336f0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
33700 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  en the.** [datab
33710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
33720 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20  is closed using 
33730 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
33740 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44  ]..**.** ^The xD
33750 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
33760 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61  is <u>not</u> ca
33770 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20  lled if the .** 
33780 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
33790 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75  ollation_v2() fu
337a0 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41  nction fails.  A
337b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
337c0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
337d0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
337e0 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20  ion_v2() with a 
337f0 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f  non-NULL xDestro
33800 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  y argument shoul
33810 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20  d .** check the 
33820 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20  return code and 
33830 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61  dispose of the a
33840 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
33850 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73  pointer.** thems
33860 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61  elves rather tha
33870 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69  n expecting SQLi
33880 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  te to deal with 
33890 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20  it for them..** 
338a0 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e  This is differen
338b0 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68  t from every oth
338c0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
338d0 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73  ace.  The incons
338e0 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75  istency .** is u
338f0 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63  nfortunate but c
33900 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
33910 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
33920 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20  g backwards .** 
33930 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
33940 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20  *.** See also:  
33950 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
33960 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64  on_needed()] and
33970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33980 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e  ion_needed16()].
33990 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
339a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
339b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
339c0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
339d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
339e0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
339f0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
33a00 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
33a10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33a20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
33a30 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
33a40 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
33a50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33a60 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
33a70 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
33a80 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
33a90 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
33aa0 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
33ab0 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
33ac0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
33ad0 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
33ae0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
33af0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c  y)(void*).);.SQL
33b00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33b10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33b20 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
33b30 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
33b40 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
33b50 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
33b60 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
33b70 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
33b80 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
33b90 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
33ba0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33bb0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
33bc0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
33bd0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
33be0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
33bf0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
33c00 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
33c10 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
33c20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
33c30 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
33c40 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
33c50 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
33c60 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
33c70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
33c80 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
33c90 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
33ca0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
33cb0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
33cc0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
33cd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
33ce0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
33cf0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
33d00 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
33d10 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
33d20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
33d30 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
33d40 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33d50 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
33d60 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
33d70 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
33d80 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33d90 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
33da0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
33db0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
33dc0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
33dd0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
33de0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
33df0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
33e00 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
33e10 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
33e20 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
33e30 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
33e40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
33e50 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33e60 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
33e70 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
33e80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
33e90 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
33ea0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
33eb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
33ec0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
33ed0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
33ee0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
33ef0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
33f00 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
33f10 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
33f20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
33f30 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
33f40 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
33f50 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
33f60 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
33f70 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
33f80 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
33f90 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
33fa0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
33fb0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
33fc0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
33fd0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
33fe0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
33ff0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
34000 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
34010 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
34020 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
34030 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
34040 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
34050 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
34060 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
34070 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
34080 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
34090 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
340a0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  on_v2()]..*/.SQL
340b0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
340c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
340d0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
340e0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
340f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
34100 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
34110 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
34120 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
34130 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
34140 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
34150 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
34160 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
34170 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
34180 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
34190 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
341a0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
341b0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
341c0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
341d0 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
341e0 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
341f0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
34200 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
34210 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
34220 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
34230 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
34240 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
34250 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
34260 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
34270 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
34280 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34290 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
342a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
342b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
342c0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
342d0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
342e0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
342f0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
34300 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
34310 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
34320 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
34330 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
34340 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
34350 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
34360 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
34370 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
34380 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
34390 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
343a0 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
343b0 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
343c0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
343d0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
343e0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
343f0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
34400 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
34410 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
34420 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
34430 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
34440 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
34450 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
34460 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
34470 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
34480 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
34490 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
344a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
344b0 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
344c0 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
344d0 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
344e0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
344f0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
34500 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
34510 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
34520 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
34530 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
34540 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34550 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
34560 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
34570 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
34580 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
34590 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
345a0 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
345b0 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
345c0 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
345d0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
345e0 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
345f0 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
34600 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
34610 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
34620 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
34630 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
34640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
34650 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
34660 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
34670 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
34680 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
34690 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
346a0 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
346b0 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
346c0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
346d0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
346e0 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
346f0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
34700 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
34710 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
34720 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
34730 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
34740 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
34750 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
34760 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
34770 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
34780 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
34790 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
347a0 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
347b0 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
347c0 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
347d0 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
347e0 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
347f0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
34800 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
34810 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
34820 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
34830 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
34840 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
34850 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
34860 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
34870 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
34880 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
34890 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
348a0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
348b0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
348c0 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
348d0 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
348e0 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
348f0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
34900 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
34910 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
34920 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
34930 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
34940 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
34950 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
34960 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
34970 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
34980 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
34990 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
349a0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
349b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
349c0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
349d0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
349e0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
349f0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
34a00 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
34a10 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
34a20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
34a30 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
34a40 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
34a50 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
34a60 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
34a70 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
34a80 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
34a90 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
34aa0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
34ab0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
34ac0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
34ad0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
34ae0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
34af0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
34b00 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34b10 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
34b20 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
34b30 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
34b40 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
34b50 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
34b60 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
34b70 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
34b80 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
34b90 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
34ba0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
34bb0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
34bc0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
34bd0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
34be0 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
34bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
34c00 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
34c10 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
34c20 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
34c30 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
34c40 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
34c50 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
34c60 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
34c70 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
34c80 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
34c90 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
34ca0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
34cb0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
34cc0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
34cd0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
34ce0 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
34cf0 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
34d00 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
34d10 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34d20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
34d30 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
34d40 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
34d50 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
34d60 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
34d70 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
34d80 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
34d90 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
34da0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34db0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
34dc0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
34dd0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
34de0 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
34df0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
34e00 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
34e10 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
34e20 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
34e30 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
34e40 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
34e50 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
34e60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
34e70 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
34e80 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
34e90 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
34ea0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
34eb0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
34ec0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
34ed0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
34ee0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
34ef0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
34f00 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
34f10 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
34f20 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
34f30 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
34f40 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
34f50 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
34f60 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c  EXTERN char *sql
34f70 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
34f80 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ory;../*.** CAPI
34f90 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41  3REF: Test For A
34fa0 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a  uto-Commit Mode.
34fb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75  ** KEYWORDS: {au
34fc0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a  tocommit mode}.*
34fd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34fe0 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74  3_get_autocommit
34ff0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
35000 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72  urns non-zero or
35010 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20  .** zero if the 
35020 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20 63  given database c
35030 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20  onnection is or 
35040 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f  is not in autoco
35050 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65  mmit mode,.** re
35060 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75  spectively.  ^Au
35070 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
35080 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a   on by default..
35090 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  ** ^Autocommit m
350a0 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  ode is disabled 
350b0 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61  by a [BEGIN] sta
350c0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f  tement..** ^Auto
350d0 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72  commit mode is r
350e0 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b  e-enabled by a [
350f0 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c  COMMIT] or [ROLL
35100 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  BACK]..**.** If 
35110 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66  certain kinds of
35120 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e   errors occur on
35130 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74   a statement wit
35140 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74  hin a multi-stat
35150 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63  ement.** transac
35160 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63  tion (errors inc
35170 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46  luding [SQLITE_F
35180 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f  ULL], [SQLITE_IO
35190 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ERR],.** [SQLITE
351a0 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45  _NOMEM], [SQLITE
351b0 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c  _BUSY], and [SQL
351c0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20  ITE_INTERRUPT]) 
351d0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e  then the.** tran
351e0 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  saction might be
351f0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
35200 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65  omatically.  The
35210 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20   only way to.** 
35220 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72  find out whether
35230 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69   SQLite automati
35240 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
35250 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
35260 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72  n after.** an er
35270 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74 68  ror is to use th
35280 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
35290 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68  ** If another th
352a0 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68 65  read changes the
352b0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74   autocommit stat
352c0 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  us of the databa
352d0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
352e0 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74   while this rout
352f0 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20  ine is running, 
35300 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
35310 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65  value.** is unde
35320 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
35330 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
35340 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
35350 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
35360 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
35370 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
35380 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
35390 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
353a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
353b0 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72 66  db_handle interf
353c0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
353d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
353e0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20  tion] handle.** 
353f0 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65 70  to which a [prep
35400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35410 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65 20 5b  belongs.  ^The [
35420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35430 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
35440 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
35450 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
35460 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35470 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20  ection].** that 
35480 77 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72  was the first ar
35490 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
354a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
354b0 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72  e_v2()] call (or
354c0 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 20 74   its variants) t
354d0 68 61 74 20 77 61 73 20 75 73 65 64 20 74 6f 0a  hat was used to.
354e0 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20 73 74  ** create the st
354f0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 66  atement in the f
35500 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53  irst place..*/.S
35510 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
35520 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
35530 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
35540 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35550 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
35560 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20   Filename For A 
35570 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
35580 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
35590 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
355a0 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(D,N) interfac
355b0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
355c0 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d  ter to a filenam
355d0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
355e0 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20  with database N 
355f0 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  of connection D.
35600 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61    ^The main data
35610 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73  base file.** has
35620 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
35630 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
35640 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  o attached datab
35650 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74  ase N on the dat
35660 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35670 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74  ion D, or if dat
35680 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d  abase N is a tem
35690 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d  porary or in-mem
356a0 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68  ory database, th
356b0 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  en.** a NULL poi
356c0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
356d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c  ..**.** ^The fil
356e0 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62  ename returned b
356f0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
35700 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  is the output of
35710 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74   the.** xFullPat
35720 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20  hname method of 
35730 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20  the [VFS].  ^In 
35740 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
35750 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c   filename.** wil
35760 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65  l be an absolute
35770 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20   pathname, even 
35780 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  if the filename 
35790 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20  used.** to open 
357a0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69  the database ori
357b0 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52  ginally was a UR
357c0 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61  I or relative pa
357d0 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53 51 4c 49 54  thname..*/.SQLIT
357e0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
357f0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c   *sqlite3_db_fil
35800 65 6e 61 6d 65 28 73 71 6c 69 74 65 33 20 2a 64  ename(sqlite3 *d
35810 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  b, const char *z
35820 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  DbName);../*.** 
35830 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
35840 69 6e 65 20 69 66 20 61 20 64 61 74 61 62 61 73  ine if a databas
35850 65 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 0a 2a  e is read-only.*
35860 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35870 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 44 2c  3_db_readonly(D,
35880 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
35890 75 72 6e 73 20 31 20 69 66 20 74 68 65 20 64 61  urns 1 if the da
358a0 74 61 62 61 73 65 20 4e 0a 2a 2a 20 6f 66 20 63  tabase N.** of c
358b0 6f 6e 6e 65 63 74 69 6f 6e 20 44 20 69 73 20 72  onnection D is r
358c0 65 61 64 2d 6f 6e 6c 79 2c 20 30 20 69 66 20 69  ead-only, 0 if i
358d0 74 20 69 73 20 72 65 61 64 2f 77 72 69 74 65 2c  t is read/write,
358e0 20 6f 72 20 2d 31 20 69 66 20 4e 20 69 73 20 6e   or -1 if N is n
358f0 6f 74 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ot.** the name o
35900 66 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  f a database on 
35910 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2f  connection D..*/
35920 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35930 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f  sqlite3_db_reado
35940 6e 6c 79 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  nly(sqlite3 *db,
35950 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
35960 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
35970 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74 68 65  PI3REF: Find the
35980 20 6e 65 78 74 20 70 72 65 70 61 72 65 64 20 73   next prepared s
35990 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
359a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  This interface r
359b0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
359c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72   to the next [pr
359d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
359e0 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74  ] after.** pStmt
359f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
35a00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
35a10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20  onnection] pDb. 
35a20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20 4e 55   ^If pStmt is NU
35a30 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  LL.** then this 
35a40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35a50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35a60 68 65 20 66 69 72 73 74 20 70 72 65 70 61 72 65  he first prepare
35a70 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61  d statement.** a
35a80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
35a90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35aa0 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66  ection pDb.  ^If
35ab0 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73 74 61   no prepared sta
35ac0 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66  tement.** satisf
35ad0 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74 69 6f  ies the conditio
35ae0 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  ns of this routi
35af0 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73 20 4e  ne, it returns N
35b00 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ULL..**.** The [
35b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35b20 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44 20 69  ion] pointer D i
35b30 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  n a call to.** [
35b40 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d  sqlite3_next_stm
35b50 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72 65 66  t(D,S)] must ref
35b60 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61  er to an open da
35b70 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
35b80 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61 72 74  tion and in part
35b90 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20  icular must not 
35ba0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
35bb0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
35bc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73   sqlite3_stmt *s
35bd0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
35be0 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
35bf0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
35c00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
35c10 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
35c20 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
35c30 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
35c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35c50 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
35c60 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
35c70 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
35c80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
35c90 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
35ca0 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
35cb0 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
35cc0 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
35cd0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
35ce0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
35cf0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
35d00 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
35d10 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
35d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35d30 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
35d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
35d50 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
35d60 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
35d70 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
35d80 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35d90 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
35da0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
35db0 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
35dc0 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
35dd0 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
35de0 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
35df0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
35e00 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
35e10 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
35e20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35e30 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
35e40 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
35e50 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
35e60 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
35e70 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
35e80 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
35e90 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
35ea0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
35eb0 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
35ec0 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
35ed0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
35ee0 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
35ef0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
35f00 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
35f10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
35f20 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
35f30 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
35f40 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
35f50 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
35f60 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
35f70 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
35f80 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
35f90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35fa0 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
35fb0 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
35fc0 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
35fd0 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
35fe0 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74  **.** The commit
35ff0 20 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f   and rollback ho
36000 6f 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65  ok callbacks are
36010 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a   not reentrant..
36020 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
36030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
36040 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
36050 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
36060 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
36070 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36080 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
36090 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20   callback.  Any 
360a0 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f  actions.** to mo
360b0 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73  dify the databas
360c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
360d0 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e  t be deferred un
360e0 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a  til after the.**
360f0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74   completion of t
36100 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
36110 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ()] call that tr
36120 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d  iggered the comm
36130 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63  it.** or rollbac
36140 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69  k hook in the fi
36150 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f  rst place..** No
36160 74 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20  te that running 
36170 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74  any other SQL st
36180 61 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64  atements, includ
36190 69 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74 65  ing SELECT state
361a0 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72  ments,.** or mer
361b0 65 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  ely calling [sql
361c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
361d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
361e0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64  step()] will mod
361f0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
36200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
36210 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
36220 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
36230 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
36240 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
36250 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
36260 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
36270 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
36280 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
36290 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
362a0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
362b0 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
362c0 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
362d0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
362e0 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
362f0 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
36300 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
36310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
36320 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
36330 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
36340 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
36350 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
36360 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
36370 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
36380 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
36390 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
363a0 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
363b0 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
363c0 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
363d0 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
363e0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
363f0 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
36400 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
36410 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
36420 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
36430 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
36440 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
36450 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
36460 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
36470 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
36480 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
36490 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
364a0 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
364b0 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
364c0 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
364d0 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
364e0 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
364f0 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
36500 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
36510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36520 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
36530 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
36540 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
36550 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61  _hook()] interfa
36560 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ce..*/.SQLITE_AP
36570 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
36580 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
36590 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
365a0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  d*), void*);.SQL
365b0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
365c0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
365d0 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ook(sqlite3*, vo
365e0 69 64 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76  id(*)(void *), v
365f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
36600 50 49 33 52 45 46 3a 20 44 61 74 61 20 43 68 61  PI3REF: Data Cha
36610 6e 67 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  nge Notification
36620 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
36630 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70   ^The sqlite3_up
36640 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  date_hook() inte
36650 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
36660 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
36670 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
36680 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36690 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64  tion] identified
366a0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
366b0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  gument.** to be 
366c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
366d0 20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65   a row is update
366e0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
366f0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  eleted..** ^Any 
36700 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20  callback set by 
36710 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  a previous call 
36720 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
36730 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
36740 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
36750 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
36760 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  en..**.** ^The s
36770 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
36780 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
36790 68 65 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69  he function to i
367a0 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20  nvoke when a.** 
367b0 72 6f 77 20 69 73 20 75 70 64 61 74 65 64 2c 20  row is updated, 
367c0 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
367d0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ted..** ^The fir
367e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
367f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
36800 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
36810 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
36820 6f 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  o sqlite3_update
36830 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e 54 68 65  _hook()..** ^The
36840 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62 61 63 6b   second callback
36850 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
36860 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 53 45   of [SQLITE_INSE
36870 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 44 45 4c  RT], [SQLITE_DEL
36880 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  ETE],.** or [SQL
36890 49 54 45 5f 55 50 44 41 54 45 5d 2c 20 64 65 70  ITE_UPDATE], dep
368a0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 70  ending on the op
368b0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 63 61 75  eration that cau
368c0 73 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  sed the callback
368d0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
368e0 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  d..** ^The third
368f0 20 61 6e 64 20 66 6f 75 72 74 68 20 61 72 67 75   and fourth argu
36900 6d 65 6e 74 73 20 74 6f 20 74 68 65 20 63 61 6c  ments to the cal
36910 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 20 70 6f  lback contain po
36920 69 6e 74 65 72 73 20 74 6f 20 74 68 65 0a 2a 2a  inters to the.**
36930 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 61   database and ta
36940 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74 61 69 6e  ble name contain
36950 69 6e 67 20 74 68 65 20 61 66 66 65 63 74 65 64  ing the affected
36960 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65 20 66 69   row..** ^The fi
36970 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 70 61 72  nal callback par
36980 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 72  ameter is the [r
36990 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 72 6f 77  owid] of the row
369a0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63 61 73  ..** ^In the cas
369b0 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65 2c 20  e of an update, 
369c0 74 68 69 73 20 69 73 20 74 68 65 20 5b 72 6f 77  this is the [row
369d0 69 64 5d 20 61 66 74 65 72 20 74 68 65 20 75 70  id] after the up
369e0 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61 63 65  date takes place
369f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 75 70  ..**.** ^(The up
36a00 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
36a10 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
36a20 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
36a30 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
36a40 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
36a50 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
36a60 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 29 5e  ite_sequence).)^
36a70 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 63  .**.** ^In the c
36a80 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
36a90 61 74 69 6f 6e 2c 20 74 68 65 20 75 70 64 61 74  ation, the updat
36aa0 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74  e hook.** is not
36ab0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 64 75   invoked when du
36ac0 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77 73 20 61  plication rows a
36ad0 72 65 20 64 65 6c 65 74 65 64 20 62 65 63 61 75  re deleted becau
36ae0 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20  se of an.** [ON 
36af0 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f  CONFLICT | ON CO
36b00 4e 46 4c 49 43 54 20 52 45 50 4c 41 43 45 5d 20  NFLICT REPLACE] 
36b10 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72 20 69 73  clause.  ^Nor is
36b20 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
36b30 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  .** invoked when
36b40 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
36b50 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74 72 75  d using the [tru
36b60 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
36b70 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78 63 65  on]..** The exce
36b80 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64 20 69  ptions defined i
36b90 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
36ba0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
36bb0 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
36bc0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
36bd0 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61 74 65  **.** The update
36be0 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e 74 61   hook implementa
36bf0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f  tion must not do
36c00 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
36c10 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
36c20 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36c30 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
36c40 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
36c50 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ok.  Any actions
36c60 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
36c70 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
36c80 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
36c90 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
36ca0 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
36cb0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
36cc0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
36cd0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
36ce0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
36cf0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
36d00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
36d10 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
36d20 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
36d30 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
36d40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
36d50 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
36d60 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
36d70 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
36d80 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ph..**.** ^The s
36d90 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
36da0 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
36db0 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  on.** returns th
36dc0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
36dd0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
36de0 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  all.** on the sa
36df0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
36e00 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
36e10 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
36e20 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20 44 2e 0a  irst call on D..
36e30 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
36e40 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 6d  he [sqlite3_comm
36e50 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20 5b  it_hook()] and [
36e60 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
36e70 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74 65  _hook()].** inte
36e80 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  rfaces..*/.SQLIT
36e90 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
36ea0 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
36eb0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
36ec0 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69  void(*)(void *,i
36ed0 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  nt ,char const *
36ee0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71  ,char const *,sq
36ef0 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20  lite3_int64),.  
36f00 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  void*.);../*.** 
36f10 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
36f20 20 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72   Or Disable Shar
36f30 65 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a  ed Pager Cache.*
36f40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61  * KEYWORDS: {sha
36f50 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a  red cache}.**.**
36f60 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
36f70 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
36f80 6c 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20  les the sharing 
36f90 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
36fa0 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68  cache.** and sch
36fb0 65 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75  ema data structu
36fc0 72 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74  res between [dat
36fd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36fe0 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a   | connections].
36ff0 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  ** to the same d
37000 61 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67  atabase. Sharing
37010 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
37020 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  he argument is t
37030 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62  rue.** and disab
37040 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
37050 65 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a  ent is false.)^.
37060 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61  **.** ^Cache sha
37070 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20  ring is enabled 
37080 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72  and disabled for
37090 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65   an entire proce
370a0 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  ss..** This is a
370b0 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51   change as of SQ
370c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
370d0 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72  .0. In prior ver
370e0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c  sions of SQLite,
370f0 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20  .** sharing was 
37100 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
37110 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72  led for each thr
37120 65 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ead separately..
37130 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68  **.** ^(The cach
37140 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
37150 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
37160 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
37170 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
37180 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
37190 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
371a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
371b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
371c0 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
371d0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
371e0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
371f0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
37200 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
37210 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
37220 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
37230 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  e opened.)^.**.*
37240 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65  * ^(This routine
37250 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
37260 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63  _OK] if shared c
37270 61 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64  ache was enabled
37280 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
37290 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41  successfully.  A
372a0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
372b0 73 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72  s returned other
372c0 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  wise.)^.**.** ^S
372d0 68 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64  hared cache is d
372e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
372f0 6c 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67  lt. But this mig
37300 68 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ht change in.** 
37310 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
37320 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c  of SQLite.  Appl
37330 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61  ications that ca
37340 72 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a  re about shared.
37350 2a 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67  ** cache setting
37360 20 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65   should set it e
37370 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a  xplicitly..**.**
37380 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c   See Also:  [SQL
37390 69 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65  ite Shared-Cache
373a0 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c 49 54 45   Mode].*/.SQLITE
373b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
373c0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
373d0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
373e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
373f0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
37400 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
37410 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
37420 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
37430 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
37440 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
37450 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
37460 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
37470 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
37480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
37490 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
374a0 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
374b0 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
374c0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
374d0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
374e0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
374f0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
37500 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
37510 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
37520 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37530 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
37540 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
37550 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
37560 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
37570 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
37580 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
37590 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
375a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
375b0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
375c0 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
375d0 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
375e0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
375f0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
37600 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
37610 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
37620 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  NT]..**.** See a
37630 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 62  lso: [sqlite3_db
37640 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
37650 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
37660 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6c   int sqlite3_rel
37670 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29  ease_memory(int)
37680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37690 46 3a 20 46 72 65 65 20 4d 65 6d 6f 72 79 20 55  F: Free Memory U
376a0 73 65 64 20 42 79 20 41 20 44 61 74 61 62 61 73  sed By A Databas
376b0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
376c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
376d0 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  db_release_memor
376e0 79 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 61  y(D) interface a
376f0 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65 20  ttempts to free 
37700 61 73 20 6d 75 63 68 20 68 65 61 70 0a 2a 2a 20  as much heap.** 
37710 6d 65 6d 6f 72 79 20 61 73 20 70 6f 73 73 69 62  memory as possib
37720 6c 65 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  le from database
37730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 55   connection D. U
37740 6e 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 5b 73 71  nlike the.** [sq
37750 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
37760 6d 6f 72 79 28 29 5d 20 69 6e 74 65 72 66 61 63  mory()] interfac
37770 65 2c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  e, this interfac
37780 65 20 69 73 20 65 66 66 65 63 74 20 65 76 65 6e  e is effect even
37790 0a 2a 2a 20 77 68 65 6e 20 74 68 65 6e 20 5b 53  .** when then [S
377a0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
377b0 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 20  ORY_MANAGEMENT] 
377c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
377d0 69 6f 6e 20 69 73 0a 2a 2a 20 6f 6d 69 74 74 65  ion is.** omitte
377e0 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
377f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 6c 65  o: [sqlite3_rele
37800 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2f  ase_memory()].*/
37810 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37820 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61  sqlite3_db_relea
37830 73 65 5f 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65  se_memory(sqlite
37840 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
37850 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
37860 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
37870 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
37880 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37890 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72 66 61  imit64() interfa
378a0 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72 20 71  ce sets and/or q
378b0 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f  ueries the.** so
378c0 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20  ft limit on the 
378d0 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
378e0 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
378f0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
37900 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74  QLite..** ^SQLit
37910 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b 65 65  e strives to kee
37920 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 74  p heap memory ut
37930 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20  ilization below 
37940 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a  the soft heap.**
37950 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75 63 69   limit by reduci
37960 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ng the number of
37970 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e 20 74   pages held in t
37980 68 65 20 70 61 67 65 20 63 61 63 68 65 0a 2a 2a  he page cache.**
37990 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   as heap memory 
379a0 75 73 61 67 65 73 20 61 70 70 72 6f 61 63 68 65  usages approache
379b0 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  s the limit..** 
379c0 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c  ^The soft heap l
379d0 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22 20 62  imit is "soft" b
379e0 65 63 61 75 73 65 20 65 76 65 6e 20 74 68 6f 75  ecause even thou
379f0 67 68 20 53 51 4c 69 74 65 20 73 74 72 69 76 65  gh SQLite strive
37a00 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c  s to stay.** bel
37a10 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20 69 74  ow the limit, it
37a20 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74 68 65   will exceed the
37a30 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20 74 68   limit rather th
37a40 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61  an generate.** a
37a50 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
37a60 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65   error.  In othe
37a70 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 6f 66  r words, the sof
37a80 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a  t heap limit .**
37a90 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c   is advisory onl
37aa0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  y..**.** ^The re
37ab0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
37ac0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
37ad0 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73 20 74  p_limit64() is t
37ae0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68  he size of.** th
37af0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37b00 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 63  t prior to the c
37b10 61 6c 6c 2c 20 6f 72 20 6e 65 67 61 74 69 76 65  all, or negative
37b20 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
37b30 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 5e 49  an.** error.  ^I
37b40 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
37b50 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20   is negative.** 
37b60 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69  then no change i
37b70 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f  s made to the so
37b80 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20  ft heap limit.  
37b90 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65  Hence, the curre
37ba0 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68  nt.** size of th
37bb0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37bc0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
37bd0 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a  ned by invoking.
37be0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  ** sqlite3_soft_
37bf0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77  heap_limit64() w
37c00 69 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61  ith a negative a
37c10 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37c20 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
37c30 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74  N is zero then t
37c40 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37c50 69 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  it is disabled..
37c60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74  **.** ^(The soft
37c70 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e   heap limit is n
37c80 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74  ot enforced in t
37c90 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
37ca0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20  mentation.** if 
37cb0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66  one or more of f
37cc0 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69  ollowing conditi
37cd0 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a  ons are true:.**
37ce0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
37cf0 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   The soft heap l
37d00 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a  imit is set to z
37d10 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d  ero..** <li> Mem
37d20 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69  ory accounting i
37d30 73 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67  s disabled using
37d40 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
37d50 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73  f the.**      [s
37d60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
37d70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
37d80 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74  MSTATUS],...) st
37d90 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  art-time option 
37da0 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  and.**      the 
37db0 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f  [SQLITE_DEFAULT_
37dc0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69  MEMSTATUS] compi
37dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
37de0 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72  ** <li> An alter
37df0 6e 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68  native page cach
37e00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37e10 20 69 73 20 73 70 65 63 69 66 69 65 64 20 75 73   is specified us
37e20 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  ing.**      [sql
37e30 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
37e40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
37e50 48 45 32 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  HE2],...)..** <l
37e60 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
37e70 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
37e80 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
37e90 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
37ea0 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
37eb0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
37ec0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
37ed0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
37ee0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
37ef0 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
37f00 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
37f10 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
37f20 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
37f30 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
37f40 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
37f50 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
37f60 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
37f70 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
37f80 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
37f90 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
37fa0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
37fb0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
37fc0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
37fd0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
37fe0 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
37ff0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
38000 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
38010 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
38020 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
38030 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
38040 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
38050 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
38060 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
38070 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
38080 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
38090 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
380a0 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
380b0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
380c0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
380d0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
380e0 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
380f0 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
38100 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
38110 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
38120 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
38130 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
38140 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
38150 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
38160 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
38170 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
38180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
38190 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
381a0 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
381b0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
381c0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
381d0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
381e0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
381f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
38200 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
38210 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
38220 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
38230 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
38240 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38250 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
38260 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
38270 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
38280 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
38290 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
382a0 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
382b0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
382c0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
382d0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
382e0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
382f0 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
38300 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
38310 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
38320 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
38330 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
38340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
38350 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
38360 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
38370 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
38380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
38390 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
383a0 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  D void sqlite3_s
383b0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
383c0 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt N);.../*.** C
383d0 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
383e0 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
383f0 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
38400 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
38410 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
38420 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
38430 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
38440 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
38450 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
38460 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
38470 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
38480 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
38490 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
384a0 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
384b0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
384c0 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
384d0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
384e0 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
384f0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
38500 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
38510 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
38520 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
38530 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
38540 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
38550 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
38560 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
38570 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
38580 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
38590 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
385a0 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
385b0 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
385c0 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
385d0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
385e0 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
385f0 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
38600 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
38610 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
38620 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
38630 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
38640 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
38650 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
38660 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
38670 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
38680 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
38690 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
386a0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
386b0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
386c0 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
386d0 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
386e0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
386f0 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
38700 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
38710 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
38720 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
38730 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
38740 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
38750 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
38760 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
38770 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
38780 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
38790 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
387a0 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
387b0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
387c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
387d0 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
387e0 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
387f0 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75